pi-chrome-search 2.0.0 → 2.1.0

package/src/engines/index.ts

@@ -19,12 +19,15 @@
  */
 
 import type { Config } from "../config/index.ts";
+import { resolveConfigPath } from "../config/env.ts";
+import { avitoEngine } from "./avito.ts";
 import { duckduckgoEngine } from "./duckduckgo.ts";
 import { googleEngine } from "./google.ts";
 import { yandexEngine } from "./yandex.ts";
 import { WebSearchError } from "../runtime/error-codes.ts";
 import {
   ENGINE_IDS,
+  isPrimaryEngine,
   type Engine,
   type EngineId,
   type EngineRegistry,
@@ -45,6 +48,7 @@ export const DEFAULT_ENGINES: EngineMap = Object.freeze({
   google: googleEngine,
   duckduckgo: duckduckgoEngine,
   yandex: yandexEngine,
+  avito: avitoEngine,
 });
 
 /**
@@ -84,13 +88,16 @@ function missingEngine(id: EngineId): WebSearchError {
 }
 
 function disabledEngine(id: EngineId): WebSearchError {
+  // S9.2: the hint names the real file and the real key, because "enable it in
+  // config" sends the agent hunting. A special engine (avito) ships disabled, so
+  // this is the first thing a user of it sees.
   return new WebSearchError({
     code: "E_UNSUPPORTED",
     engine: id,
     stage: "resolve",
     retryable: false,
     message: `engine "${id}" is disabled in config`,
-    hint: `set config.engines.${id}.enabled = true (or pick another engine); /web-doctor shows the current state`,
+    hint: `set config.engines.${id}.enabled = true in ${resolveConfigPath(process.env)} (or pick another engine); /web-doctor shows the current state`,
   });
 }
 
@@ -122,8 +129,10 @@ class Registry implements EngineRegistry {
 
   select(requested: EngineSelection): EngineId[] {
     const usable = new Set(this.enabled());
-    // `auto` is the canonical order by construction: `enabled()` walks ENGINE_IDS.
-    if (requested === "auto") return this.enabled();
+    // `auto` is the canonical order by construction: `enabled()` walks ENGINE_IDS,
+    // and the primary filter is what keeps a special engine (avito) out of it
+    // (SPEC S4.7/D11). A caller that wants it names it.
+    if (requested === "auto") return this.enabled().filter(isPrimaryEngine);
 
     const list = Array.isArray(requested) ? requested : [requested];
     const selected: EngineId[] = [];

package/src/engines/types.ts

@@ -9,10 +9,40 @@
 
 import type { CdpPage } from "../cdp/types.ts";
 
-export type EngineId = "google" | "duckduckgo" | "yandex";
+/**
+ * Primary engines answer a general web query. Canonical order; `auto` keeps this
+ * order and yandex stays last by policy (SPEC §15 D10).
+ */
+export const PRIMARY_ENGINES = ["google", "duckduckgo", "yandex"] as const;
+
+/**
+ * Special engines answer one site, not the web (SPEC §15 D11). They are never
+ * part of `auto`: a marketplace listing is not an answer to "search the web",
+ * so a caller must name the engine (`engines: "avito"`) to get it.
+ */
+export const SPECIAL_ENGINES = ["avito"] as const;
 
-/** Canonical order. `auto` keeps this order; yandex stays last by policy (D10). */
-export const ENGINE_IDS = ["google", "duckduckgo", "yandex"] as const satisfies readonly EngineId[];
+export type PrimaryEngineId = (typeof PRIMARY_ENGINES)[number];
+export type SpecialEngineId = (typeof SPECIAL_ENGINES)[number];
+export type EngineId = PrimaryEngineId | SpecialEngineId;
+
+/** Every id the contract knows, primary first. `auto` walks the primary part only. */
+export const ENGINE_IDS = [...PRIMARY_ENGINES, ...SPECIAL_ENGINES] as const satisfies readonly EngineId[];
+
+export type EngineClass = "primary" | "special";
+
+/** Primary/special is data, so `auto` and the tool's docs cannot drift apart. */
+export const ENGINE_CLASS: Readonly<Record<EngineId, EngineClass>> = Object.freeze({
+  google: "primary",
+  duckduckgo: "primary",
+  yandex: "primary",
+  avito: "special",
+});
+
+/** True when `auto` may pick this engine (SPEC S4.7). */
+export function isPrimaryEngine(id: EngineId): boolean {
+  return ENGINE_CLASS[id] === "primary";
+}
 
 export interface Query {
   text: string;
@@ -42,6 +72,17 @@ export interface SerpItem {
    * resolved link (S3.5, S7.4).
    */
   unresolved?: boolean;
+  /**
+   * Short facts the card shows around the snippet, in display order: price,
+   * availability, rating, location, listing date (SPEC §15 D13).
+   *
+   * Additive and optional on purpose: a SERP that does not surface them leaves
+   * this absent, and an adapter never invents one. Google already prints
+   * `103 500,00 ₽ · В наличии · 5,0 ★` under some results; Avito prints price,
+   * location and date on every card. The renderer joins them after the snippet
+   * and caps the line (`COMPACT_CAPS.factsMaxChars`).
+   */
+  facts?: readonly string[];
 }
 
 /**
@@ -121,6 +162,15 @@ export interface RawSerp {
   pageCarried: boolean;
   /** True only for the keyless HTTP fallback (SPEC §6.5); never for a real SERP. */
   degraded?: boolean;
+  /**
+   * One adapter-authored line about the page the caller must not have to guess
+   * (S7.6/S7.7): Avito answers a no-match query with "similar listings", and
+   * saying so is the difference between a labelled fallback and a silent lie.
+   *
+   * A fixed adapter constant, never page text — a SERP cannot inject prose into
+   * the output through it.
+   */
+  notice?: string;
   timings: SerpTimings;
 }
 
@@ -171,6 +221,12 @@ export interface EngineInteraction {
   minCount?: number;
   /** Optional typing profile; without it `humanize: "typing"` uses the generic delays. */
   typeProfile?: EngineTypeProfile;
+  /**
+   * Per-query home page, when the engine's home is parameterized (SPEC D12:
+   * Avito's typed search starts on `https://www.avito.ru/<location>/`, so the
+   * configured region must reach the warm-up page too). Absent means `homeUrl`.
+   */
+  homeUrlFor?(q: Query): string;
   /**
    * Where the typed path starts (P10-C). `home` (default) opens the engine home
    * page and types into its box. `serp` navigates the SERP URL first and types
@@ -216,11 +272,14 @@ export type ArgumentSupport = "yes" | "flag";
 export const SUPPORT_MATRIX: Readonly<
   Record<SupportArgument, Readonly<Record<EngineId, ArgumentSupport>>>
 > = Object.freeze({
-  n: Object.freeze({ google: "yes", duckduckgo: "yes", yandex: "yes" }),
+  n: Object.freeze({ google: "yes", duckduckgo: "yes", yandex: "yes", avito: "yes" }),
   // DuckDuckGo has no pagination in this adapter: page > 1 is served as page 1
   // and must be reported as `ignored.page`, never silently dropped (S4.2, S7.1).
-  page: Object.freeze({ google: "yes", duckduckgo: "flag", yandex: "yes" }),
-  summary: Object.freeze({ google: "yes", duckduckgo: "yes", yandex: "yes" }),
+  // Avito paginates with `&p=` (verified live: the page-2 link carries `p=2`).
+  page: Object.freeze({ google: "yes", duckduckgo: "flag", yandex: "yes", avito: "yes" }),
+  // Avito has no native AI block at all (SPEC D12): asking is reported as
+  // `ignored.summary`, never answered with an invented summary.
+  summary: Object.freeze({ google: "yes", duckduckgo: "yes", yandex: "yes", avito: "flag" }),
 });
 
 export interface EngineRegistry {

package/src/engines/yandex.ts

@@ -29,6 +29,7 @@
 
 import type { CdpPage } from "../cdp/types.ts";
 import { waitForMarker } from "../cdp/humanize.ts";
+import { asFacts } from "../extract/facts.ts";
 import { normalizeUrl } from "../extract/urls.ts";
 import { systemClock } from "../runtime/clock.ts";
 import { fail } from "../runtime/errors.ts";
@@ -134,6 +135,8 @@ export interface YandexExtractedItem {
   title: string;
   url: string;
   snippet: string;
+  /** Card facts (S7.7): a shop rating and its review count, when shown. */
+  facts?: string[];
 }
 
 export interface YandexExtractedAi {
@@ -543,11 +546,33 @@ export function extractFromDocument(doc: Document, arg: YandexExtractionArg): Ya
     organics += 1;
 
     let snippet = "";
+    const facts: string[] = [];
     if (card !== null) {
-      const snippetElement = card.querySelector(".OrganicTextContentSpan");
+      // `.OrganicTextContent` is today's layout (`yandex-rating`), the
+      // `…Span` wrapper is the older one (`yandex-neuro`): the old selector alone
+      // returned empty snippets on a live SERP.
+      const snippetElement = card.querySelector(".OrganicTextContentSpan, .OrganicTextContent");
       if (snippetElement !== null) snippet = normalize(snippetElement.textContent);
+
+      /**
+       * A shop rating, not a product rating: the card prints "Рейтинг 4,4 из 5"
+       * and "414K отзывов на магазин". Both strings are copied, never
+       * recomposed, so the label that says what the rating is about survives
+       * into the output (S7.7: report, do not invent).
+       */
+      const label = card.querySelector('[class*="EReviewsLabel"]');
+      if (label !== null) {
+        const ratingNode = label.querySelector(".A11yHidden");
+        const rating = ratingNode === null ? "" : normalize(ratingNode.textContent);
+        if (rating !== "") facts.push(rating);
+        const reviewsNode = label.querySelector('[class*="EReviewsLabel-Reviews"]');
+        const reviews = reviewsNode === null ? "" : normalize(reviewsNode.textContent);
+        if (reviews !== "") facts.push(reviews);
+      }
+    }
+    if (results.length < limit) {
+      results.push({ title, url, snippet, ...(facts.length === 0 ? {} : { facts }) });
     }
-    if (results.length < limit) results.push({ title, url, snippet });
   }
 
   /**
@@ -728,7 +753,8 @@ function asExtraction(value: unknown): { results: SerpItem[]; ai: AiSummary | un
     const normalized = normalizeUrl(url);
     if (normalized === null || seenUrls.has(normalized)) continue;
     seenUrls.add(normalized);
-    results.push({ title, url: normalized, snippet });
+    const facts = asFacts(rawItem.facts);
+    results.push({ title, url: normalized, snippet, ...(facts.length === 0 ? {} : { facts }) });
   }
 
   let ai: AiSummary | undefined;

package/src/extract/compact.ts

@@ -25,11 +25,13 @@
  *   "ai": { "text": "…", "sources": ["a.com"] },   // omitted when absent
  *   "results": [
  *     { "title": "…", "url": "…", "domain": "…", "snippet": "…", "engine": "google",
- *       "unresolved": true }
+ *       "unresolved": true, "facts": ["23 990 ₽", "Самара"] }
  *     // "engine" only when the caller mixed engines; "unresolved" only for an
- *     // opaque Google /goto wrapper that stayed unresolved (S3.5, S7.4)
+ *     // opaque Google /goto wrapper that stayed unresolved (S3.5, S7.4); "facts"
+ *     // only when the card showed price/rating/location (SPEC §15 D13)
  *   ],
  *   "pageCarried": true,
+ *   "notice": "no exact match: …",       // only when the engine answered with a fallback
  *   "ignored": { "page": "duckduckgo" }, // only when an argument was not honoured
  *   "degraded": true,                   // only when true
  *   "cached": true,                     // only when true
@@ -65,6 +67,12 @@ export const COMPACT_CAPS = {
   maxN: 10,
   /** Results per domain before the domain cap starts deferring them. */
   perDomainLimit: 2,
+  /**
+   * Card facts joined on one line (`23 990 ₽ · Самара · Вчера`, SPEC §15 D13).
+   * A fact line is display sugar: it never displaces the snippet, and it is cut
+   * here so an adapter cannot flood the output with page text.
+   */
+  factsMaxChars: 120,
 } as const;
 
 export interface CompactOptions {
@@ -99,6 +107,8 @@ export interface CompactItem {
   engine?: EngineId;
   /** The URL is an opaque `/goto` wrapper that stayed unresolved (S3.5, S7.4). */
   unresolved?: boolean;
+  /** Card facts (price, location, date) rendered after the snippet; already capped. */
+  facts?: readonly string[];
 }
 
 export interface CompactAi {
@@ -118,6 +128,8 @@ export interface CompactResult {
   pageCarried: boolean;
   degraded: boolean;
   cached: boolean;
+  /** Adapter-authored caveat about the page (`no exact match: …`); rendered as `note: `. */
+  notice?: string;
   /** Markdown render (always produced). */
   text: string;
   /** JSON render; see the schema above. */
@@ -137,6 +149,7 @@ interface MergedItem {
   snippet: string;
   engine?: EngineId;
   unresolved?: boolean;
+  facts?: readonly string[];
 }
 
 interface Opts {
@@ -182,6 +195,30 @@ const AI_MIN_BLOCK = AI_NEWLINE + AI_PREFIX.length + 1;
  */
 const AI_SOURCES_MAX_SHARE = 0.25;
 const PAGE_LINE = "\npage: more results available";
+/** Card facts are one line, joined the way a SERP card groups them. */
+const FACTS_SEPARATOR = " · ";
+/** Adapter notice is one short line (`note: …`), never a paragraph. */
+const NOTICE_MAX_CHARS = 160;
+
+/**
+ * Cap a card's facts as a joined line by dropping whole facts from the tail.
+ * A truncated price ("23 9…") would be a wrong price, and a wrong price is worse
+ * than a missing one, so facts are never cut mid-way.
+ */
+function capFacts(facts: readonly string[] | undefined): string[] | undefined {
+  if (facts === undefined) return undefined;
+  const kept: string[] = [];
+  let width = 0;
+  for (const raw of facts) {
+    const fact = collapse(raw);
+    if (fact === "") continue;
+    const extra = kept.length === 0 ? fact.length : fact.length + FACTS_SEPARATOR.length;
+    if (width + extra > COMPACT_CAPS.factsMaxChars) break;
+    kept.push(fact);
+    width += extra;
+  }
+  return kept.length === 0 ? undefined : kept;
+}
 
 function clampInt(value: number | undefined, fallback: number, min: number, max: number): number {
   if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
@@ -361,6 +398,9 @@ function renderItem(item: CompactItem, index: number): string {
   const marker = item.unresolved === true ? " (unresolved)" : "";
   const lines = [`${index + 1}. ${heading}`, `   ${item.url}${marker}`];
   if (item.snippet) lines.push(`   ${item.snippet}`);
+  if (item.facts !== undefined && item.facts.length > 0) {
+    lines.push(`   ${item.facts.join(FACTS_SEPARATOR)}`);
+  }
   return lines.join("\n");
 }
 
@@ -373,6 +413,7 @@ function jsonItem(item: CompactItem): Record<string, unknown> {
   };
   if (item.engine) out.engine = item.engine;
   if (item.unresolved === true) out.unresolved = true;
+  if (item.facts !== undefined && item.facts.length > 0) out.facts = [...item.facts];
   return out;
 }
 
@@ -418,6 +459,13 @@ export function compactSerps(serps: readonly RawSerp[], options: CompactOptions)
   const engineLabel = contributing.length === 0 ? "none" : contributing.join("+");
   const query = collapse(input[0]?.query ?? "");
   const degraded = input.some((serp) => serp.degraded === true);
+  // Adapter-authored notice (S7.6): "Avito answered with similar listings". One
+  // line, first non-empty wins, capped — a page cannot push prose through it
+  // because adapters pass a constant, not page text.
+  const notice = truncate(
+    collapse(input.find((serp) => typeof serp.notice === "string" && serp.notice !== "")?.notice ?? ""),
+    NOTICE_MAX_CHARS,
+  );
 
   const merged = new Map<string, MergedItem>();
   for (const serp of input) {
@@ -430,6 +478,7 @@ export function compactSerps(serps: readonly RawSerp[], options: CompactOptions)
 
       const title = truncate(collapse(raw.title), COMPACT_CAPS.titleMaxChars);
       const snippet = truncate(collapse(raw.snippet), opts.snippetMaxChars);
+      const facts = capFacts(raw.facts);
       const engine = raw.engine ?? serp.engine;
       const existing = merged.get(normalized);
 
@@ -441,14 +490,16 @@ export function compactSerps(serps: readonly RawSerp[], options: CompactOptions)
           snippet,
           engine,
           ...(raw.unresolved === true ? { unresolved: true } : {}),
+          ...(facts === undefined ? {} : { facts }),
         });
         continue;
       }
 
-      // First non-empty title wins; the longest capped snippet wins (ties keep
-      // the earlier engine, so the outcome does not depend on map internals).
+      // First non-empty title/facts win; the longest capped snippet wins (ties
+      // keep the earlier engine, so the outcome does not depend on map internals).
       if (!existing.title && title) existing.title = title;
       if (snippet.length > existing.snippet.length) existing.snippet = snippet;
+      if (existing.facts === undefined && facts !== undefined) existing.facts = facts;
       if (raw.unresolved === true) existing.unresolved = true;
     }
   }
@@ -518,6 +569,7 @@ export function compactSerps(serps: readonly RawSerp[], options: CompactOptions)
 
   const render = (items: CompactItem[], summary: CompactAi | undefined, state: AiState): string => {
     const head = [headerFor(items, state)];
+    if (notice !== "") head.push(`note: ${notice}`);
     if (summary) head.push(aiLine(summary));
     let text = head.join("\n");
     if (items.length > 0) text += `\n\n${items.map(renderItem).join("\n")}`;
@@ -534,12 +586,14 @@ export function compactSerps(serps: readonly RawSerp[], options: CompactOptions)
     };
     if (mixed || perEngine) out.engine = item.engine;
     if (item.unresolved === true) out.unresolved = true;
+    if (item.facts !== undefined && item.facts.length > 0) out.facts = item.facts;
     return out;
   };
 
   const outputMaxChars = opts.outputMaxChars;
   const fallbackCap = Math.min(opts.snippetMaxChars, MIN_SNIPPET);
   const pageSuffixLen = pageCarried ? PAGE_LINE.length : 0;
+  const noticeLen = notice === "" ? 0 : `\nnote: ${notice}`.length;
 
   // Results floor: the exact chars needed for the selected items at MIN_SNIPPET.
   // Titles are already capped by the merge step and URLs are full, so this is an
@@ -551,7 +605,7 @@ export function compactSerps(serps: readonly RawSerp[], options: CompactOptions)
   // `headerFor(selected.length, …)` is the widest header still possible: dropping
   // tail items only shortens the count, and `ai:lead` (7) is the widest AI label.
   const headerReserve =
-    headerFor(selected.map((item) => toItem(item, fallbackCap)), "lead").length + pageSuffixLen;
+    headerFor(selected.map((item) => toItem(item, fallbackCap)), "lead").length + pageSuffixLen + noticeLen;
   const aiBudget = Math.max(
     0,
     Math.min(opts.summaryMaxChars, outputMaxChars - headerReserve - resultsFloor),
@@ -617,6 +671,7 @@ export function compactSerps(serps: readonly RawSerp[], options: CompactOptions)
   }
   if (aiOut) data.ai = { text: aiOut.text, sources: [...aiOut.sources], state: "answer" };
   if (aiState === "lead") data.aiState = "lead";
+  if (notice !== "") data.notice = notice;
   if (degraded) data.degraded = true;
   if (opts.cached) data.cached = true;
 
@@ -634,6 +689,7 @@ export function compactSerps(serps: readonly RawSerp[], options: CompactOptions)
     resultsChars,
     truncated,
   };
+  if (notice !== "") result.notice = notice;
   if (aiOut) result.ai = aiOut;
   return result;
 }

package/src/extract/facts.ts

@@ -0,0 +1,39 @@
+/**
+ * Card facts (SPEC S7.7, §15 D13): the short strings a SERP card shows *outside*
+ * its snippet — a price, an availability, a rating, a place, an age.
+ *
+ * Why one module: three adapters (avito, google, yandex) report facts, and an
+ * adapter must not be able to disagree about how many a card may carry or how
+ * long one may be. The display cap (one joined line, 120 chars) lives in
+ * `compact.ts`; this is the *input* cap, applied to untrusted page output before
+ * it becomes a `SerpItem`.
+ *
+ * Facts are copied from the page, never composed from numbers we found: "От
+ * 4 057,00 ₽" and "Рейтинг 4,4 из 5" are the page's own words, so a fact cannot
+ * claim more than the SERP did. A fact is dropped whole when it does not fit —
+ * half a price is worse than no price.
+ */
+
+/** A card with more than four facts is reporting a table, not a card. */
+export const FACT_MAX_ITEMS = 4;
+
+/** Longer than this is prose that belongs in the snippet (57 + margin). */
+export const FACT_MAX_CHARS = 60;
+
+/**
+ * Guard for the TS side of the page boundary: the DOM is untrusted even when we
+ * wrote the extractor. Non-strings, blanks and over-long fragments are dropped;
+ * the count and the length are capped.
+ */
+export function asFacts(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  const facts: string[] = [];
+  for (const raw of value) {
+    if (typeof raw !== "string") continue;
+    const fact = raw.replace(/[\s\u00a0\u202f]+/g, " ").trim();
+    if (fact === "") continue;
+    facts.push(fact.slice(0, FACT_MAX_CHARS));
+    if (facts.length >= FACT_MAX_ITEMS) break;
+  }
+  return facts;
+}

package/src/runtime/doctor.ts

@@ -69,8 +69,18 @@ const WALL_KINDS = ["captcha", "consent", "sorry", "blocked"] as const;
  * `skipped` means "not exercised" (caller asked for no probe, or CDP was down),
  * which is different from `unavailable` ("tried and could not"). It still keeps
  * the overall verdict at `degraded`: a doctor with no evidence is not healthy.
+ *
+ * `disabled` is the one exception: an engine the user turned off (the opt-in
+ * avito ships off, SPEC D12) is a config choice, not a fault.
  */
-export type EngineVerdict = "ok" | "wall" | "layout_changed" | "blocked" | "unavailable" | "skipped";
+export type EngineVerdict =
+  | "ok"
+  | "wall"
+  | "layout_changed"
+  | "blocked"
+  | "unavailable"
+  | "skipped"
+  | "disabled";
 export type CdpStatus = "ok" | "unavailable" | "busy" | "error" | "awaiting_allow";
 export type DoctorVerdict = "ok" | "degraded" | "blocked";
 
@@ -138,6 +148,11 @@ function probeLocale(engine: EngineId, config: Config): Pick<Query, "lang" | "re
       const region = resolveProbeLocale(config.engines.yandex.lr);
       return region === undefined ? {} : { region };
     }
+    case "avito": {
+      // `auto` means every region here; the adapter's own default is `all` too.
+      const region = resolveProbeLocale(config.engines.avito.location);
+      return region === undefined ? {} : { region };
+    }
   }
 }
 
@@ -827,7 +842,10 @@ async function engineEntry(
 ): Promise<DoctorEngine> {
   const enabled = deps.config.engines[id].enabled;
   if (!enabled) {
-    return { id, enabled: false, verdict: "unavailable", note: "disabled in config" };
+    // A deliberate config choice, reported as `disabled` so it does not degrade
+    // the verdict: the opt-in avito engine ships off (SPEC D12), and a fresh
+    // install must not look broken because of it.
+    return { id, enabled: false, verdict: "disabled", note: "disabled in config" };
   }
 
   if (!deps.registry.has(id)) {
@@ -948,7 +966,12 @@ async function readArtifacts(artifacts: Artifacts | undefined): Promise<DoctorAr
 
 function overallVerdict(cdp: DoctorCdp, engines: DoctorEngine[]): DoctorVerdict {
   if (cdp.status !== "ok" || cdp.webdriver === true) return "blocked";
-  if (engines.some((engine) => engine.verdict !== "ok")) return "degraded";
+  // `disabled` (an engine the user turned off, e.g. the opt-in avito) is a config
+  // choice, not a fault: only a broken, unavailable or probe-skipped engine
+  // degrades the report ("probe absence is not health").
+  if (engines.some((engine) => engine.verdict !== "ok" && engine.verdict !== "disabled")) {
+    return "degraded";
+  }
   return "ok";
 }
 

package/src/runtime/limiter.ts

@@ -29,11 +29,11 @@ interface EngineCounters {
 }
 
 function emptyCounters(): Record<EngineId, EngineCounters> {
-  return {
-    google: { lastAt: null, today: 0 },
-    duckduckgo: { lastAt: null, today: 0 },
-    yandex: { lastAt: null, today: 0 },
-  };
+  // Derived from ENGINE_IDS so a new engine cannot be missing from the counters
+  // (SPEC §15 D11: the wiring is data, not a second list to keep in sync).
+  const counters = {} as Record<EngineId, EngineCounters>;
+  for (const id of ENGINE_IDS) counters[id] = { lastAt: null, today: 0 };
+  return counters;
 }
 
 function cancelled(engine: EngineId): WebSearchError {

package/src/runtime/panel.ts

@@ -29,7 +29,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 
 import type { PageKey } from "../cdp/types.ts";
 import type { PacingWindow } from "../config/index.ts";
-import type { EngineId } from "../engines/types.ts";
+import { ENGINE_IDS, type EngineId } from "../engines/types.ts";
 import type { Clock } from "./types.ts";
 
 /** Highest number of panel paints per second (PLAN-v2 P10-A). */
@@ -136,7 +136,7 @@ const STAGES: ReadonlySet<string> = new Set<PanelStage>([
   "error",
 ]);
 
-const ENGINES: ReadonlySet<string> = new Set<EngineId>(["google", "duckduckgo", "yandex"]);
+const ENGINES: ReadonlySet<string> = new Set<string>(ENGINE_IDS);
 
 /** Control characters would corrupt the rendered single line; strip, never escape. */
 function clean(value: string, max: number): string {

package/src/tools/web_search.ts

@@ -67,17 +67,23 @@ const engineIdSchema = Type.Union([
   Type.Literal("google"),
   Type.Literal("duckduckgo"),
   Type.Literal("yandex"),
+  Type.Literal("avito"),
 ]);
 
 /**
  * SPEC §7.1 / D9. `engines` accepts one id, a list, or `auto`; the array form is
- * capped at three because that is every engine the extension supports.
+ * capped at `ENGINE_IDS.length` because that is every engine the extension
+ * supports.
  */
 export const webSearchSchema = Type.Object({
   q: Type.String({ minLength: 1 }),
   n: Type.Optional(Type.Integer({ minimum: 1, maximum: 10 })),
   engines: Type.Optional(
-    Type.Union([Type.Literal("auto"), engineIdSchema, Type.Array(engineIdSchema, { minItems: 1, maxItems: 3 })]),
+    Type.Union([
+      Type.Literal("auto"),
+      engineIdSchema,
+      Type.Array(engineIdSchema, { minItems: 1, maxItems: ENGINE_IDS.length }),
+    ]),
   ),
   summary: Type.Optional(Type.Boolean()),
   page: Type.Optional(Type.Integer({ minimum: 1 })),
@@ -192,7 +198,7 @@ export interface WebSearchTool {
  * every word.
  */
 export const WEB_SEARCH_DESCRIPTION =
-  "Search the web for free in the user's visible Chrome (Google, DuckDuckGo, Yandex) with each engine's native AI summary. Compact results, n<=10. Call web_read on a result URL to get that page as paged Markdown. site:/filetype:/quoted queries pass through; engines: id, list, or auto.";
+  "Search the web for free in the user's visible Chrome (Google, DuckDuckGo, Yandex; Avito listings opt-in) with each engine's native AI summary. Compact results, n<=10. Call web_read on a result URL to get that page as paged Markdown. site:/filetype:/quoted queries pass through; engines: id, list, or auto.";
 
 /**
  * SPEC S3.6: `q` is passed verbatim, so narrowing happens in the query. The
@@ -200,6 +206,7 @@ export const WEB_SEARCH_DESCRIPTION =
  */
 export const WEB_SEARCH_GUIDELINES: readonly string[] = [
   "web_search passes q verbatim: use quoted phrases, -term, OR, site:, filetype:; narrow by date with after:/before: on Google or date: on Yandex (there is no date argument).",
+  "engines:\"avito\" searches Avito listings (price, location); it is opt-in: enable engines.avito.enabled in web-search.json first, and auto never uses it.",
 ];
 
 /**
@@ -217,8 +224,7 @@ const FALLBACK_CODES: ReadonlySet<ErrorCode> = new Set<ErrorCode>([
 ]);
 
 /** Every defensive validation failure shares this hint: the fix is in the call, not the file. */
-const INPUT_HINT =
-  "check the web_search arguments: q (non-empty), n 1..10, page >= 1, engines auto|google|duckduckgo|yandex";
+const INPUT_HINT = `check the web_search arguments: q (non-empty), n 1..10, page >= 1, engines auto|${ENGINE_IDS.join("|")}`;
 
 const UNSUPPORTED_HINT =
   "no enabled engine matched the request; run /web-doctor (or node src/cli/doctor.ts --json) and check config.engines";
@@ -350,7 +356,13 @@ function resolveLocale(value: string): string | undefined {
  * parameter rather than inventing one.
  */
 function buildQuery(engine: EngineId, input: NormalizedInput, config: Config): Query {
-  const query: Query = { text: input.q, n: input.n, summary: input.summary };
+  const query: Query = {
+    text: input.q,
+    n: input.n,
+    // S4.2 as data: an engine without a native AI block (avito) never receives
+    // `summary: true`; the caller sees `ignored.summary` instead (S7.1).
+    summary: SUPPORT_MATRIX.summary[engine] === "yes" ? input.summary : false,
+  };
   // S4.2 is data (`SUPPORT_MATRIX`): an engine that cannot paginate never
   // receives `page`, and the caller is told so through `ignored` below.
   if (SUPPORT_MATRIX.page[engine] === "yes") query.page = input.page;
@@ -373,6 +385,12 @@ function buildQuery(engine: EngineId, input: NormalizedInput, config: Config): Q
       if (region !== undefined) query.region = region;
       break;
     }
+    case "avito": {
+      // The region is a URL path slug, not a locale; `auto` means "every
+      // region" here, which is the adapter's own default (SPEC D12).
+      query.region = resolveLocale(config.engines.avito.location) ?? "all";
+      break;
+    }
   }
   return query;
 }
@@ -967,7 +985,7 @@ async function runEngineLive(
       const human = await humanSearch({
         page,
         query: query.text,
-        homeUrl: interaction.homeUrl,
+        homeUrl: interaction.homeUrlFor?.(query) ?? interaction.homeUrl,
         serpUrl: engine.buildUrl(query),
         boxSelectors: [...interaction.boxSelectors],
         marker: interaction.marker,
@@ -1209,6 +1227,20 @@ export function createWebSearchTool(
       return failureResult(asFailure(error, "resolve"));
     }
     if (order.length === 0) {
+      // The selection came back empty. When the caller named engines, ask the
+      // registry *why* each one was dropped: a disabled engine (the opt-in avito
+      // ships off, D12) gets its own "set config.engines.avito.enabled" hint
+      // instead of a generic "no enabled engine" (S9.2). `auto` keeps the
+      // generic message: there is no id to explain.
+      const named =
+        input.engines === "auto" ? [] : Array.isArray(input.engines) ? input.engines : [input.engines];
+      for (const id of named) {
+        try {
+          deps.engines.get(id);
+        } catch (error) {
+          return failureResult(asFailure(error, "resolve", id));
+        }
+      }
       return failureResult(
         fail("E_UNSUPPORTED", "resolve", {
           hint: UNSUPPORTED_HINT,