pi-chrome-search 0.1.1 → 2.1.0

package/README.md

@@ -1,90 +1,66 @@
 # pi-chrome-search
-Free, keyless web search for [pi](https://pi.dev) through **your own, visible Chrome** — same profile,
-same cookies, same IP — returning compact Markdown from Google, DuckDuckGo and Yandex with each engine's
-native AI summary (AI Overview, Search Assist, "Быстрый ответ Алисы AI"), plus page reading and image
-search. The window staying visible is intentional: you can watch the search and solve a captcha yourself.
-It is not an automation browser: raw CDP, one owned window, one work tab per engine, ≤2500 chars of
-output, every failure carrying a code, a stage and a hint. No paid search APIs, no keys, no captcha
-solving, no fingerprint spoofing, no headless mode.
+
+[![npm](https://img.shields.io/npm/v/pi-chrome-search)](https://www.npmjs.com/package/pi-chrome-search)
+[![downloads](https://img.shields.io/npm/dm/pi-chrome-search)](https://www.npmjs.com/package/pi-chrome-search)
+[![pi](https://img.shields.io/badge/pi-package-6f42c1)](https://pi.dev/packages)
+[![ci](https://github.com/sh2nk/pi-chrome-search/actions/workflows/ci.yml/badge.svg)](https://github.com/sh2nk/pi-chrome-search/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/pi-chrome-search)](LICENSE)
+[![node](https://img.shields.io/badge/node-%3E%3D26-brightgreen)](package.json)
+
+Web search and page reading for [pi](https://pi.dev), through your own visible Chrome. Same profile,
+cookies and IP. Google, DuckDuckGo and Yandex return compact Markdown and their native AI summary when
+there is one; Avito listings (price, location, age) are available opt-in. No keys, no paid APIs, no
+headless mode, no fingerprint spoofing. Node 26+, Chrome 136+.
 
 ## Install
-Node ≥ 26 (native TypeScript, no build step), Chrome 136+ (tested on 157, Wayland), pi, a headed desktop
-session. Then `/web-doctor` inside pi must report a live CDP endpoint and `navigator.webdriver === false`.
 
 ```bash
-npm install            # ws + typescript (dev); no build step
-pi install .           # register this checkout as a pi package
-pi -e ./src/index.ts   # …or load it for one throwaway session
+pi install npm:pi-chrome-search
 ```
 
-## Enable CDP (once per Chrome session)
-Chrome 136+ ignores `--remote-debugging-port` for the default profile; debugging is enabled from inside
-the browser and needs an explicit **Allow** click.
+Chrome 136+ enables debugging only after an explicit click:
 
-1. Open `chrome://inspect/#remote-debugging` in the Chrome window the agent should use.
-2. Tick **Discover network targets**, then click **Allow** on the prompt.
-3. Check the endpoint file (line 1 = port, line 2 = `/devtools/browser/<uuid>`):
-   `cat ~/.config/google-chrome/DevToolsActivePort`
+1. Open `chrome://inspect/#remote-debugging`.
+2. Tick **Discover network targets**, then click **Allow**.
 
-`curl 127.0.0.1:9222/json/version` may return nothing in this mode — expected; the file is authoritative.
-Discovery order: `PI_CHROME_CDP_WS` → `PI_CHROME_CDP_PORTS` → `DevToolsActivePort` → `cdp.ports`. The
-extension never launches, restarts or kills Chrome, never edits your profile, never closes foreign tabs.
+The window stays visible. The extension attaches to it and never launches, restarts or closes Chrome.
 
 ## Tools
-`web_search` is `direct`; everything else is `deferred` (tool search + `codemode`, not paid per prompt).
-All descriptions together stay under 900 characters.
 
+`web_search` and `web_read` are direct. The other three sit behind `tool_search`.
+
+<!-- tools:start -->
 | Tool | Exposure | Arguments |
 |---|---|---|
-| `web_search` | direct | `q`; `n` 1–10 (5); `engines` `auto`\|id\|list; `summary` (true); `freshness` `d\|w\|m\|y`; `page`; `format` `md\|json` |
-| `web_read` | deferred | `url` (http/https); `offset`; `maxChars` (6000, ceiling 20000); `format` `md\|text` |
-| `image_search` | deferred | `q`; `n` ≤12 (4); `engine` `google\|yandex`; `attach` (≤4 thumbnails) |
-| `web_research` | deferred | `q`; `budget` `quick` (1 search + 2 reads) \| `normal` (2+4) \| `deep` (4+8) |
-| `web_doctor` | deferred | `probe` (true), `fix` (false: reconnect, close owned tabs, prune artifacts) |
-
-Output is capped at 2500 chars (summary ≤1200, snippets ≤140). The AI block has three states: `ai:yes`
-only for ≥200 chars of prose, `ai:lead` (block present, no answer — never rendered as one), `ai:no`.
-
-## Configuration
-`~/.pi/agent/web-search.json` (or `$PI_CODING_AGENT_DIR/web-search.json`), optional and strict: an
-unknown key is `E_CONFIG`. All keys: [`docs/config.md`](docs/config.md). The six that matter most:
-`engines.google.enabled` (`true`, per-engine switch) · `search.n` (`5`, ≤`search.nMax` 10) ·
-`search.aiWaitMs` (`6000`, bounded AI-block wait) · `read.maxCharsCeiling` (`20000`) ·
-`window.follow` (`"work"`, which tab is raised during a stage) · `reflex.pageGate` (`true`,
-source-quality gate in `web_research`, rules floor in `web_read`).
-
-Env overrides: `PI_CHROME_CDP_WS`, `PI_CHROME_CDP_PORTS`, `PI_CHROME_SEARCH_PROFILE`,
-`PI_CHROME_SEARCH_DEBUG`, `PI_CODING_AGENT_DIR`. System 1 triage stays off (`reflex.enabled: false`):
-the benchmark showed no honest token win.
-
-## When it fails
-| Code | Action |
-|---|---|
-| `E_CDP_UNAVAILABLE` | Open `chrome://inspect/#remote-debugging`, tick **Discover network targets**, click **Allow**; or set `PI_CHROME_CDP_WS` |
-| `E_CDP_AWAITING_ALLOW` | The prompt is waiting; click it — the call resumes by itself (`cdp.attachWaitMs`, 60 s) |
-| `E_WALL` | A captcha/consent page: solve it in the visible window, then retry. Never automated |
-| `E_BUSY` | Another pi session holds `~/.pi/agent/web-search.lock`: close it or wait for the heartbeat |
-| `E_PARSE` | A selector canary failed: open the artifact dir, compare `page.txt` with `docs/engines.md` |
-
-All 18 codes with hints: [`docs/errors.md`](docs/errors.md). `/web-doctor` (or
-`node src/cli/doctor.ts --json`) is the first stop; `--fix` reconnects, closes only owned tabs and prunes
-artifacts under `~/.pi/agent/web-search/`.
-
-## Security and ToS
-Your session, your cookies: searches and reads happen in your browser as you. `web_read` can open pages
-you are logged into but never exfiltrates content, and it refuses loopback/private/`file:`/`data:` URLs
-(re-checked on redirect). No telemetry; artifacts are sanitized and git-ignored. CDP is powerful — any
-local process that reaches the debugging port can drive the browser; it binds loopback only and you
-enable it explicitly. The optional page gate sends only URL/title/snippet of ≤10 sources (never page
-text) to your configured classifier; `reflex.localOnly: true` keeps it local.
-
-Google and Yandex prohibit automated access in their terms: this project does not claim compliance and
-must not be run as a service. If an engine shows a captcha, solve it in the window or stop.
-
-## Development
-`npm run lint` (typecheck + audit) · `npm test` (offline contract suite) · `npm run test:live` (opt-in,
-one query per engine, no retries, `PI_CHROME_LIVE=1`). Decisions: [`docs/architecture.md`](docs/architecture.md)
-· selectors: [`docs/engines.md`](docs/engines.md). Never launch a browser from tests; never loop probes.
-
-## License
-MIT — see [`LICENSE`](LICENSE).
+| `web_search` | direct | `q` string; `n?` integer 1..10; `engines?` "auto" or ("google" or "duckduckgo" or "yandex" or "avito") or list of ("google" or "duckduckgo" or "yandex" or "avito") 1..4; `summary?` boolean; `page?` integer >=1; `format?` "md" or "json" |
+| `web_read` | direct | `url` string; `offset?` integer >=0; `maxChars?` integer >=1; `format?` "md" or "text" |
+| `image_search` | deferred | `q` string; `n?` integer 1..12; `engine?` "google" or "yandex"; `attach?` boolean or "bytes" |
+| `web_research` | deferred | `q` string; `budget?` "quick" or "normal" or "deep" |
+| `web_doctor` | deferred | `probe?` boolean; `fix?` boolean |
+<!-- tools:end -->
+
+A call has one 60 second deadline. DuckDuckGo has no pagination: `page > 1` is reported as
+`ignored.page`; Avito has no AI block: `summary` is reported as `ignored.summary`. Every unresolved
+link stays marked `unresolved`, and card facts (price/availability/rating/location) render on their
+own line after the snippet.
+
+`engines: "auto"` only ever means Google → DuckDuckGo → Yandex. Avito is a *special* engine: it is off
+by default and reachable only by naming it. To turn it on, set `engines.avito.enabled` to `true` (and
+optionally `engines.avito.location`, a region slug such as `kaluga` or `all`) in
+`~/.pi/agent/web-search.json` — ask your agent to do it, that is the intended path.
+
+## Limits
+
+No headless browsing, automation profile, captcha solving, proxy rotation, cookie export, telemetry or
+paid search API. Google and Yandex forbid automated access in their terms. If a captcha appears, solve it
+in the window or stop.
+
+## Failures
+
+Every failure is an `E_*` code with a stage, a retry flag and a hint you can act on. The full table is in
+[errors.md](https://github.com/sh2nk/pi-chrome-search/blob/main/docs/errors.md). Start with
+`/web-doctor` or `node src/cli/doctor.ts --json`.
+
+Config reference: [config.md](https://github.com/sh2nk/pi-chrome-search/blob/main/docs/config.md).
+
+MIT.

package/assets/anchor.html

@@ -83,7 +83,7 @@
   </section>
 
   <section class="card">
-    <h2>Daily counters</h2>
+    <h2>Session counters</h2>
     <table>
       <tbody>
         <tr><td>google</td><td class="num" id="count-google">—</td></tr>
@@ -135,7 +135,7 @@
       var cell = counters[entry.engine];
       if (!cell) continue;
       seen[entry.engine] = true;
-      cell.textContent = String(entry.today) + " / " + String(entry.cap);
+      cell.textContent = String(entry.today);
     }
     for (var name in counters) {
       if (!seen[name] && counters[name]) counters[name].textContent = "—";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-chrome-search",
-  "version": "0.1.1",
-  "description": "Free, keyless web search through the user's own visible Chrome (Google, DuckDuckGo, Yandex) for pi",
+  "version": "2.1.0",
+  "description": "Free, keyless web search through the user's own visible Chrome (Google, DuckDuckGo, Yandex, and opt-in Avito listings) for pi",
   "type": "module",
   "license": "MIT",
   "pi": {
@@ -18,6 +18,9 @@
     "test": "node --test --test-timeout=15000 \"tests/unit/**/*.test.ts\"",
     "test:live": "PI_CHROME_LIVE=1 node --test \"tests/live/**/*.test.ts\"",
     "audit": "node scripts/audit.mjs",
+    "gen-config-doc": "node scripts/gen-config-doc.mjs",
+    "gen-errors-doc": "node scripts/gen-errors-doc.mjs",
+    "gen-readme": "node scripts/gen-readme.mjs",
     "release": "node scripts/release.mjs"
   },
   "peerDependencies": {
@@ -42,7 +45,8 @@
     "web-search",
     "google",
     "duckduckgo",
-    "yandex"
+    "yandex",
+    "avito"
   ],
   "files": [
     "index.ts",

package/src/cdp/bytes.ts

@@ -24,7 +24,7 @@
 
 import { isWebSearchError } from "../runtime/error-codes.ts";
 import { fail } from "../runtime/errors.ts";
-import type { CdpSession } from "./session.ts";
+import type { CdpClient } from "./types.ts";
 import type { FetchedBytes, FetchBytesOptions } from "./types.ts";
 
 export const DEFAULT_FETCH_TIMEOUT_MS = 20_000;
@@ -95,7 +95,7 @@ async function withDeadline<T>(work: Promise<T>, timeoutMs: number, url: string)
  * is the final hop, and the tool re-runs the guard on it before using the body.
  */
 export async function captureBytes(
-  session: CdpSession,
+  client: CdpClient,
   url: string,
   options: FetchBytesOptions = {},
 ): Promise<FetchedBytes> {
@@ -113,15 +113,15 @@ export async function captureBytes(
   try {
     // `background: true` keeps the user's foreground tab where it is; Chrome
     // 132+ accepts it and older builds ignore the flag rather than failing.
-    targetId = await session.createTarget("about:blank", { background: true });
-    await session.attach(targetId);
-    sessionId = session.sessionIdFor(targetId);
+    targetId = await client.createTarget("about:blank", { background: true });
+    await client.attach(targetId);
+    sessionId = client.sessionIdFor(targetId);
     if (sessionId === undefined) {
       throw fail("E_CDP_DISCONNECTED", "connect", { message: "the capture target is not attached" });
     }
     const captureSessionId = sessionId;
 
-    await session.send(
+    await client.send(
       "Fetch.enable",
       { patterns: [{ urlPattern: "*", requestStage: "Response" }] },
       captureSessionId,
@@ -157,7 +157,7 @@ export async function captureBytes(
 
           // Redirects are part of the chain; keep following until the body hop.
           if (status >= 300 && status < 400) {
-            void session
+            void client
               .send("Fetch.continueResponse", { requestId }, captureSessionId)
               .catch(() => undefined);
             return;
@@ -165,7 +165,7 @@ export async function captureBytes(
 
           const declared = contentLength(headers);
           if (declared !== undefined && declared > maxBytes) {
-            void session.send("Fetch.failRequest", { requestId, errorReason: "Aborted" }, captureSessionId).catch(
+            void client.send("Fetch.failRequest", { requestId, errorReason: "Aborted" }, captureSessionId).catch(
               () => undefined,
             );
             finish(() =>
@@ -185,7 +185,7 @@ export async function captureBytes(
 
           void (async () => {
             try {
-              const body = await session.send<Record<string, unknown>>(
+              const body = await client.send<Record<string, unknown>>(
                 "Fetch.getResponseBody",
                 { requestId },
                 captureSessionId,
@@ -209,18 +209,18 @@ export async function captureBytes(
             } catch (error) {
               finish(() => reject(error));
             } finally {
-              void session
+              void client
                 .send("Fetch.failRequest", { requestId, errorReason: "Aborted" }, captureSessionId)
                 .catch(() => undefined);
             }
           })();
         };
 
-        onEvent = session.on("Fetch.requestPaused", handler);
+        onEvent = client.on("Fetch.requestPaused", handler);
         // The request is opened by the document, not by `Page.navigate`: the
         // capture target never shows a PDF viewer, so there is no "load" to
         // await and no viewer document to mistake for the payload.
-        void session
+        void client
           .send(
             "Runtime.evaluate",
             {
@@ -248,10 +248,10 @@ export async function captureBytes(
     });
   } finally {
     if (sessionId !== undefined) {
-      await session.send("Fetch.disable", {}, sessionId).catch(() => undefined);
+      await client.send("Fetch.disable", {}, sessionId).catch(() => undefined);
     }
     if (targetId !== undefined) {
-      await session.closeTarget(targetId).catch(() => undefined);
+      await client.closeTarget(targetId).catch(() => undefined);
     }
   }
 }