pi-chrome-search 0.1.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (62) hide show
  1. package/README.md +37 -76
  2. package/assets/anchor.html +2 -2
  3. package/package.json +4 -1
  4. package/src/cdp/bytes.ts +14 -14
  5. package/src/cdp/client.ts +687 -0
  6. package/src/cdp/page.ts +716 -0
  7. package/src/cdp/readiness.ts +119 -0
  8. package/src/cdp/shared.ts +70 -0
  9. package/src/cdp/types.ts +30 -1
  10. package/src/cli/doctor.ts +14 -17
  11. package/src/commands/focus.ts +2 -2
  12. package/src/config/defaults.ts +158 -0
  13. package/src/config/doc.ts +180 -0
  14. package/src/config/env.ts +58 -0
  15. package/src/config/index.ts +10 -0
  16. package/src/config/load.ts +40 -0
  17. package/src/config/schema.ts +264 -0
  18. package/src/engines/duckduckgo.ts +7 -10
  19. package/src/engines/google.ts +11 -21
  20. package/src/engines/images.ts +1 -1
  21. package/src/engines/index.ts +5 -13
  22. package/src/engines/types.ts +29 -6
  23. package/src/engines/yandex.ts +11 -18
  24. package/src/extract/claims.ts +1 -1
  25. package/src/extract/compact.ts +29 -3
  26. package/src/extract/goto.ts +124 -2
  27. package/src/extract/text.ts +43 -0
  28. package/src/index.ts +52 -80
  29. package/src/runtime/artifacts.ts +6 -11
  30. package/src/runtime/attention.ts +2 -2
  31. package/src/runtime/budget.ts +142 -0
  32. package/src/runtime/cache.ts +1 -3
  33. package/src/runtime/doctor.ts +17 -43
  34. package/src/runtime/error-codes.ts +19 -8
  35. package/src/runtime/errors-doc.ts +45 -0
  36. package/src/runtime/limiter.ts +33 -221
  37. package/src/runtime/log.ts +2 -2
  38. package/src/runtime/panel.ts +30 -4
  39. package/src/runtime/types.ts +2 -17
  40. package/src/{cdp/discovery.ts → session/discover.ts} +3 -3
  41. package/src/session/index.ts +34 -0
  42. package/src/session/lock.ts +346 -0
  43. package/src/{cdp → session}/page-lock.ts +12 -13
  44. package/src/session/session.ts +684 -0
  45. package/src/session/tabs.ts +277 -0
  46. package/src/tools/image_search.ts +21 -7
  47. package/src/tools/index.ts +18 -7
  48. package/src/tools/surface.ts +97 -0
  49. package/src/tools/types.ts +2 -5
  50. package/src/tools/web_doctor.ts +2 -2
  51. package/src/tools/web_read.ts +159 -114
  52. package/src/tools/web_research.ts +33 -207
  53. package/src/tools/web_search.ts +208 -419
  54. package/src/version.ts +12 -3
  55. package/src/cdp/browser.ts +0 -1286
  56. package/src/cdp/session.ts +0 -1446
  57. package/src/config.ts +0 -651
  58. package/src/reflex/classifier.ts +0 -1578
  59. package/src/reflex/index.ts +0 -172
  60. package/src/reflex/policy.ts +0 -792
  61. package/src/reflex/rules.ts +0 -557
  62. package/src/reflex/types.ts +0 -117
@@ -0,0 +1,119 @@
1
+ /**
2
+ * Document readiness for `web_read` (SPEC S5.1, S5.2).
3
+ *
4
+ * `navigate()` resolves at a *commit* and waits for `readyState interactive`,
5
+ * which is the right bar for a SERP but not for an article: a client-rendered
6
+ * page can be interactive with an empty body and paint its text a moment later.
7
+ * v1 extracted immediately in that state, so a JS-heavy page came back as a
8
+ * misleading `E_PARSE` with no text (SPEC appendix). This module adds the read
9
+ * bar on top of the navigation bar:
10
+ *
11
+ * readyState >= interactive AND (visible text >= 200 chars OR complete)
12
+ *
13
+ * The 200-char floor is the point: an interactive SPA with a shell is not ready,
14
+ * while a complete short page (`complete` wins) is. The wait is bounded by a
15
+ * soft deadline (2.5 s) that is itself clamped by the call budget. There is no
16
+ * `loadEventFired` dependency and no fixed settle sleep: each probe is a
17
+ * one-off `Runtime.evaluate`, and the poll interval backs off between a short
18
+ * first look and a 250 ms cap.
19
+ *
20
+ * `waitForDocumentReadiness` never throws on "not ready": it returns the last
21
+ * observation and lets the caller extract what is there. A complete but empty
22
+ * document is the caller's `E_EMPTY_PAGE`, not a readiness timeout. Only the
23
+ * clock abort (budget/caller) or a transport failure propagates.
24
+ */
25
+
26
+ import type { CdpPage } from "./types.ts";
27
+ import type { Clock } from "../runtime/types.ts";
28
+
29
+ /** SPEC S5.1: a document with this much visible text is readable while interactive. */
30
+ export const READINESS_TEXT_FLOOR = 200;
31
+ /** SPEC S5.1: soft deadline inside the call budget; not a navigation timeout. */
32
+ export const READINESS_SOFT_DEADLINE_MS = 2500;
33
+ /** First look: a page that paints synchronously must not pay a settle sleep. */
34
+ export const READINESS_FIRST_POLL_MS = 50;
35
+ /** Upper bound for one poll interval; keeps the deadline arithmetic predictable. */
36
+ export const READINESS_MAX_POLL_MS = 250;
37
+
38
+ /**
39
+ * One self-contained probe. It runs in the page, so it uses only `document` and
40
+ * returns by value; `page.evaluate` is a one-off `Runtime.evaluate` (hard rule
41
+ * 3 forbids `addScriptToEvaluateOnNewDocument`, not this).
42
+ */
43
+ export const READINESS_PROBE = `(() => {
44
+ const body = document.body;
45
+ const raw = body === null ? "" : (body.innerText || body.textContent || "");
46
+ return { readyState: document.readyState, textChars: raw.replace(/\\s+/g, " ").trim().length };
47
+ })()`;
48
+
49
+ export interface DocumentReadiness {
50
+ /** `document.readyState`: loading, interactive or complete. */
51
+ readyState: string;
52
+ /** Visible text length after whitespace normalisation. */
53
+ textChars: number;
54
+ }
55
+
56
+ export interface ReadinessOutcome {
57
+ ready: boolean;
58
+ /** Last observation, useful in the failure artifact/message. */
59
+ state: DocumentReadiness;
60
+ /** True when the soft deadline arrived while the document was still thin. */
61
+ softDeadlineHit: boolean;
62
+ }
63
+
64
+ export interface ReadinessOptions {
65
+ clock: Clock;
66
+ /** Soft deadline in ms; the caller clamps it to the remaining call budget. */
67
+ softDeadlineMs?: number;
68
+ /** Call budget/caller abort; wins over the soft deadline. */
69
+ signal?: AbortSignal;
70
+ }
71
+
72
+ function safeState(value: unknown): DocumentReadiness {
73
+ if (typeof value !== "object" || value === null) return { readyState: "loading", textChars: 0 };
74
+ const record = value as Record<string, unknown>;
75
+ const readyState = typeof record.readyState === "string" ? record.readyState : "loading";
76
+ const textChars =
77
+ typeof record.textChars === "number" && Number.isFinite(record.textChars)
78
+ ? Math.max(0, Math.floor(record.textChars))
79
+ : 0;
80
+ return { readyState, textChars };
81
+ }
82
+
83
+ /** SPEC S5.1, in one place so the probe and the tests cannot drift. */
84
+ export function isDocumentReady(state: DocumentReadiness): boolean {
85
+ if (state.readyState === "complete") return true;
86
+ if (state.readyState !== "interactive") return false;
87
+ return state.textChars >= READINESS_TEXT_FLOOR;
88
+ }
89
+
90
+ /**
91
+ * Poll until the document is ready or the soft deadline expires. The page is
92
+ * never navigated or modified; only `document.readyState` and the visible text
93
+ * length are read.
94
+ */
95
+ export async function waitForDocumentReadiness(
96
+ page: CdpPage,
97
+ options: ReadinessOptions,
98
+ ): Promise<ReadinessOutcome> {
99
+ const requested = Number.isFinite(options.softDeadlineMs)
100
+ ? Math.max(0, Math.floor(options.softDeadlineMs as number))
101
+ : READINESS_SOFT_DEADLINE_MS;
102
+ const deadline = options.clock.now() + Math.min(requested, READINESS_SOFT_DEADLINE_MS);
103
+ let interval = READINESS_FIRST_POLL_MS;
104
+
105
+ for (;;) {
106
+ const state = safeState(await page.evaluate<unknown>(READINESS_PROBE));
107
+ if (isDocumentReady(state)) {
108
+ return { ready: true, state, softDeadlineHit: false };
109
+ }
110
+
111
+ const remaining = deadline - options.clock.now();
112
+ if (remaining <= 0) {
113
+ return { ready: false, state, softDeadlineHit: true };
114
+ }
115
+
116
+ await options.clock.sleep(Math.min(interval, remaining), options.signal);
117
+ interval = Math.min(READINESS_MAX_POLL_MS, interval * 2);
118
+ }
119
+ }
@@ -0,0 +1,70 @@
1
+ /**
2
+ * Small, dependency-free helpers shared by the raw client and the document
3
+ * layer. They are here so `client.ts` stays a socket and `page.ts` stays a
4
+ * document, without either exporting the other's internals.
5
+ */
6
+
7
+ import { setTimeout as sleepFor } from "node:timers/promises";
8
+
9
+ import type { ErrorCode, Stage } from "../runtime/error-codes.ts";
10
+ import { WebSearchError } from "../runtime/error-codes.ts";
11
+ import { toFailure } from "../runtime/errors.ts";
12
+ import type { Clock } from "../runtime/types.ts";
13
+
14
+ export const realClock: Clock = {
15
+ now: () => Date.now(),
16
+ sleep: (ms, signal) =>
17
+ signal === undefined ? sleepFor(ms) : sleepFor(ms, undefined, { signal }),
18
+ };
19
+
20
+ export function isRecord(value: unknown): value is Record<string, unknown> {
21
+ return typeof value === "object" && value !== null && !Array.isArray(value);
22
+ }
23
+
24
+ export function asString(value: unknown): string | undefined {
25
+ return typeof value === "string" ? value : undefined;
26
+ }
27
+
28
+ export function positiveTimeout(value: number | undefined, fallback: number): number {
29
+ if (typeof value === "number" && Number.isFinite(value) && value > 0) return Math.floor(value);
30
+ return fallback;
31
+ }
32
+
33
+ /** Typing delays allow 0, unlike connect/request deadlines. */
34
+ export function nonNegativeDelay(value: number | undefined, fallback: number): number {
35
+ if (typeof value === "number" && Number.isFinite(value) && value >= 0) return Math.floor(value);
36
+ return fallback;
37
+ }
38
+
39
+ export function finiteNumber(value: unknown): number | undefined {
40
+ return typeof value === "number" && Number.isFinite(value) ? value : undefined;
41
+ }
42
+
43
+ /** Read `aborted` through a call so control-flow narrowing cannot hide a later abort. */
44
+ export function isAborted(signal?: AbortSignal): boolean {
45
+ return signal?.aborted === true;
46
+ }
47
+
48
+ /** Main frame id + current document loaderId from a `Page.getFrameTree` response. */
49
+ export function mainFrameOf(tree: unknown): { frameId?: string; loaderId?: string } {
50
+ const root = isRecord(tree) && isRecord(tree.frameTree) ? tree.frameTree : undefined;
51
+ const frame = root !== undefined && isRecord(root.frame) ? root.frame : undefined;
52
+ if (frame === undefined) return {};
53
+ return { frameId: asString(frame.id), loaderId: asString(frame.loaderId) };
54
+ }
55
+
56
+ /**
57
+ * `location.href` comes back normalised by the renderer (`https://host` is
58
+ * reported as `https://host/`), so the fallback comparison tolerates the one
59
+ * trailing slash Chrome adds.
60
+ */
61
+ export function sameNavigatedUrl(current: string, requested: string): boolean {
62
+ if (current === requested) return true;
63
+ const trim = (value: string): string => (value.endsWith("/") ? value.slice(0, -1) : value);
64
+ return trim(current) === trim(requested);
65
+ }
66
+
67
+ export function asWebSearchError(error: unknown, fallback: ErrorCode, stage: Stage): WebSearchError {
68
+ if (error instanceof WebSearchError) return error;
69
+ return new WebSearchError(toFailure(error, { code: fallback, stage }));
70
+ }
package/src/cdp/types.ts CHANGED
@@ -104,6 +104,35 @@ export interface BrowserInfo {
104
104
  jsVersion: string;
105
105
  }
106
106
 
107
+ /** Clock surface the client needs; `runtime/types.ts` `Clock` satisfies it. */
108
+ export interface CdpClock {
109
+ now(): number;
110
+ sleep(ms: number, signal?: AbortSignal): Promise<void>;
111
+ }
112
+
113
+ export type CdpEventHandler = (params: Record<string, unknown>, sessionId?: string) => void;
114
+
115
+ /**
116
+ * The raw transport seam. `CdpClient` in `client.ts` is the production
117
+ * implementation; the session tests inject a fake through `connectClient` so
118
+ * connect refusal, Allow waits, drops and closed tabs are offline scenarios.
119
+ */
120
+ export interface CdpClient {
121
+ readonly clock?: CdpClock;
122
+ isConnected(): boolean;
123
+ version(): Promise<BrowserInfo>;
124
+ targets(): Promise<CdpTarget[]>;
125
+ attach(targetId: string): Promise<{ targetId: string; sessionId: string }>;
126
+ detach(sessionId: string): Promise<void>;
127
+ createTarget(url: string, opts?: { newWindow?: boolean; background?: boolean }): Promise<string>;
128
+ closeTarget(targetId: string): Promise<void>;
129
+ send<T>(method: string, params?: Record<string, unknown>, sessionId?: string): Promise<T>;
130
+ on(method: string, handler: CdpEventHandler): () => void;
131
+ close(): Promise<void>;
132
+ sessionIdFor(targetId: string): string | undefined;
133
+ targetUrlFor(targetId: string): string | undefined;
134
+ }
135
+
107
136
  export interface CdpTarget {
108
137
  id: string;
109
138
  type: string;
@@ -119,7 +148,7 @@ export interface CdpConnectionInfo {
119
148
  webdriver: boolean;
120
149
  }
121
150
 
122
- /** Implemented by cdp/browser.ts (P1-D). Tools never touch raw sockets. */
151
+ /** Implemented by `src/session/`. (PLAN P3.) Tools never touch raw sockets. */
123
152
  export interface CdpConnector {
124
153
  connect(): Promise<CdpConnectionInfo>;
125
154
  /** One owned work tab per engine, reused across calls. */
package/src/cli/doctor.ts CHANGED
@@ -6,7 +6,7 @@
6
6
  * and prints it. The CLI owns the three things the report module must not do
7
7
  * itself:
8
8
  *
9
- * - **A real connector.** A fresh `createConnector` with the system clock and a
9
+ * - **A real connector.** A fresh `createSession` with the system clock and a
10
10
  * JSONL log under `~/.pi/agent/web-search/doctor.jsonl`. The log is created
11
11
  * only when this process builds the connector (an injected test connector
12
12
  * must not write into the user's agent dir).
@@ -29,12 +29,10 @@
29
29
  import { join, resolve } from "node:path";
30
30
  import { pathToFileURL } from "node:url";
31
31
 
32
- import { createConnector } from "../cdp/browser.ts";
33
- import type { Connector, ConnectorOptions } from "../cdp/browser.ts";
34
- import { defaultLockPath } from "../cdp/browser.ts";
35
- import { discoverEndpoint } from "../cdp/discovery.ts";
36
- import { loadConfig, resolveConfigPath } from "../config.ts";
37
- import type { Config } from "../config.ts";
32
+ import { createSession, defaultLockPath, discoverEndpoint } from "../session/index.ts";
33
+ import type { Session, SessionOptions } from "../session/index.ts";
34
+ import { loadConfig, resolveConfigPath } from "../config/index.ts";
35
+ import type { Config } from "../config/index.ts";
38
36
  import { createDefaultRegistry } from "../engines/index.ts";
39
37
  import { createAllowAttention, oscNotification, type AllowAttention } from "../runtime/attention.ts";
40
38
  import type { EngineRegistry } from "../engines/types.ts";
@@ -83,16 +81,16 @@ export interface DoctorCliDeps {
83
81
  clock?: Clock;
84
82
  loadConfig?: (opts: { path?: string; env: NodeJS.ProcessEnv }) => Config;
85
83
  /** Pre-built connector (tests). When set, no logger is created. */
86
- connector?: Connector;
87
- createConnector?: (options: ConnectorOptions) => Connector;
84
+ connector?: Session;
85
+ createSession?: (options: SessionOptions) => Session;
88
86
  registry?: EngineRegistry;
89
87
  cache?: Cache;
90
88
  artifacts?: Artifacts;
91
89
  probe?: EngineProbe;
92
90
  /**
93
91
  * Pacing for the live probe. Production leaves it unset and gets the real
94
- * limiter over `~/.pi/agent/web-search/state.json`, so `--fix`/`--json` never
95
- * fire three unthrottled searches (AGENTS §2 rule 7); tests inject a fake.
92
+ * in-memory limiter, so `--fix`/`--json` never fire three unthrottled searches
93
+ * (AGENTS §2 rule 7); tests inject a fake.
96
94
  */
97
95
  limiter?: Limiter;
98
96
  /**
@@ -257,13 +255,13 @@ export async function runDoctorCli(
257
255
  // connector (tests, or a caller with its own log) never gets a file here.
258
256
  let log: Logger | undefined = deps.log;
259
257
 
260
- let connector: Connector;
258
+ let connector: Session;
261
259
  try {
262
260
  if (deps.connector !== undefined) {
263
261
  connector = deps.connector;
264
262
  } else {
265
263
  log ??= createLogger({ path: join(stateDir(env), "doctor.jsonl"), clock });
266
- connector = (deps.createConnector ?? createConnector)({
264
+ connector = (deps.createSession ?? createSession)({
267
265
  config,
268
266
  discover: () =>
269
267
  discoverEndpoint({
@@ -291,9 +289,8 @@ export async function runDoctorCli(
291
289
  // The same runtime objects the extension uses: the probe acquires an owned
292
290
  // work tab through this connector, extracts with the real adapters and paces
293
291
  // through the same limiter as `web_search`. The factory itself is lazy, so
294
- // `--no-probe` never touches the browser; the limiter only reads its state.
295
- const limiter =
296
- deps.limiter ?? createLimiter({ config, clock, statePath: join(stateDir(env), "state.json") });
292
+ // `--no-probe` never touches the browser.
293
+ const limiter = deps.limiter ?? createLimiter({ config, clock });
297
294
  const probe: EngineProbe =
298
295
  deps.probe ?? createEngineProbe({ config, connector, registry, clock, limiter });
299
296
 
@@ -386,7 +383,7 @@ export async function runDoctorCli(
386
383
  return report.verdict === "blocked" ? DOCTOR_BLOCKED_EXIT_CODE : 0;
387
384
  }
388
385
 
389
- async function releaseQuietly(connector: Connector): Promise<void> {
386
+ async function releaseQuietly(connector: Session): Promise<void> {
390
387
  try {
391
388
  if (connector.isConnected()) await connector.releaseAll();
392
389
  } catch {
@@ -8,12 +8,12 @@
8
8
  * that is the one case where focusing opens something.
9
9
  */
10
10
 
11
- import type { Connector } from "../cdp/browser.ts";
11
+ import type { Session } from "../session/index.ts";
12
12
  import { toFailure } from "../runtime/errors.ts";
13
13
  import type { NotifyContext } from "./doctor.ts";
14
14
 
15
15
  export interface FocusDeps {
16
- connector?: Connector;
16
+ connector?: Session;
17
17
  }
18
18
 
19
19
  export type FocusDepsFactory = () => FocusDeps | Promise<FocusDeps>;
@@ -0,0 +1,158 @@
1
+ /**
2
+ * The config contract: one type tree, one default tree (S13.1).
3
+ *
4
+ * Every leaf here is read by production code; `scripts/audit.mjs` fails when a
5
+ * leaf has no reader (S13.2). Removed surfaces (SPEC §15) do not come back:
6
+ * there is no attach/launch mode, no classifier block, no wall retry, no daily
7
+ * caps and no profile-directory key. `PI_CHROME_SEARCH_PROFILE` is a host
8
+ * discovery input, not configuration.
9
+ */
10
+
11
+ export type FocusPolicy = "session" | "always" | "never";
12
+ export type FollowPolicy = "work" | "anchor" | "never";
13
+ export type HumanizeMode = "auto" | "always" | "typing";
14
+
15
+ export interface CdpConfig {
16
+ ports: number[];
17
+ ws: string | null;
18
+ connectTimeoutMs: number;
19
+ /** How long an attach may wait for the user's CDP Allow (S8.4); `0` disables the wait. */
20
+ attachWaitMs: number;
21
+ }
22
+
23
+ export interface WindowConfig {
24
+ focus: FocusPolicy;
25
+ /** Best-effort raise while the Allow prompt is waiting; `never` keeps the session passive. */
26
+ raiseOnPrompt: "auto" | "never";
27
+ /** Host the local anchor panel instead of `about:blank`. */
28
+ panel: boolean;
29
+ /** Which tab is raised during and after a stage. */
30
+ follow: FollowPolicy;
31
+ /** ms after the last stage before the anchor is raised again. */
32
+ idleMs: number;
33
+ }
34
+
35
+ export interface GoogleConfig {
36
+ enabled: boolean;
37
+ lang: string;
38
+ gl: string;
39
+ }
40
+
41
+ export interface DuckDuckGoConfig {
42
+ enabled: boolean;
43
+ kl: string;
44
+ }
45
+
46
+ export interface YandexConfig {
47
+ enabled: boolean;
48
+ lr: string;
49
+ }
50
+
51
+ export interface EnginesConfig {
52
+ google: GoogleConfig;
53
+ duckduckgo: DuckDuckGoConfig;
54
+ yandex: YandexConfig;
55
+ }
56
+
57
+ export type PacingWindow = [number, number];
58
+
59
+ export interface PacingConfig {
60
+ google: PacingWindow;
61
+ duckduckgo: PacingWindow;
62
+ yandex: PacingWindow;
63
+ }
64
+
65
+ export interface SearchConfig {
66
+ /** Whole-call deadline, from the first live attempt to the rendered result (S8.1). */
67
+ budgetMs: number;
68
+ n: number;
69
+ nMax: number;
70
+ summaryMaxChars: number;
71
+ snippetMaxChars: number;
72
+ outputMaxChars: number;
73
+ /** Bounded wait for a streaming native AI summary; 0 disables waiting. */
74
+ aiWaitMs: number;
75
+ /** Allow one visible expand click inside the AI block; default off. */
76
+ aiExpand: boolean;
77
+ }
78
+
79
+ export interface ReadConfig {
80
+ /** Whole-call deadline in ms: navigation, readiness, extraction and the PDF ladder (S8.1). */
81
+ budgetMs: number;
82
+ defaultMaxChars: number;
83
+ maxCharsCeiling: number;
84
+ /** Concurrent read slots, each with its own tab and exclusive lock (S5.7). */
85
+ pool: number;
86
+ /** Hard ceiling for a fetched PDF. */
87
+ pdfMaxBytes: number;
88
+ /** Keep the fetched PDF bytes next to the text artifact; default off. */
89
+ keepPdf: boolean;
90
+ /** Per-page text cap before the next `--- p.N ---` marker. */
91
+ pdfPageMaxChars: number;
92
+ }
93
+
94
+ export interface ImageConfig {
95
+ /** Per-thumbnail byte ceiling for `attach:"bytes"`. */
96
+ attachMaxBytes: number;
97
+ }
98
+
99
+ export interface CacheConfig {
100
+ serpTtlMs: number;
101
+ gotoTtlMs: number;
102
+ maxEntries: number;
103
+ }
104
+
105
+ export interface ArtifactsConfig {
106
+ enabled: boolean;
107
+ keep: number;
108
+ maxBytes: number;
109
+ }
110
+
111
+ export interface Config {
112
+ cdp: CdpConfig;
113
+ window: WindowConfig;
114
+ humanize: HumanizeMode;
115
+ engines: EnginesConfig;
116
+ pacing: PacingConfig;
117
+ search: SearchConfig;
118
+ read: ReadConfig;
119
+ image: ImageConfig;
120
+ cache: CacheConfig;
121
+ artifacts: ArtifactsConfig;
122
+ debug: boolean;
123
+ }
124
+
125
+ export const DEFAULT_CONFIG: Config = {
126
+ cdp: { ports: [9222], ws: null, connectTimeoutMs: 5000, attachWaitMs: 60000 },
127
+ window: { focus: "session", raiseOnPrompt: "auto", panel: true, follow: "work", idleMs: 1500 },
128
+ humanize: "auto",
129
+ engines: {
130
+ google: { enabled: true, lang: "auto", gl: "auto" },
131
+ duckduckgo: { enabled: true, kl: "auto" },
132
+ yandex: { enabled: true, lr: "auto" },
133
+ },
134
+ pacing: { google: [2500, 5000], yandex: [5000, 9000], duckduckgo: [2000, 4000] },
135
+ search: {
136
+ budgetMs: 60000,
137
+ n: 5,
138
+ nMax: 10,
139
+ summaryMaxChars: 1200,
140
+ snippetMaxChars: 140,
141
+ outputMaxChars: 2500,
142
+ aiWaitMs: 6000,
143
+ aiExpand: false,
144
+ },
145
+ read: {
146
+ budgetMs: 30000,
147
+ defaultMaxChars: 6000,
148
+ maxCharsCeiling: 20000,
149
+ pool: 1,
150
+ pdfMaxBytes: 20 * 1024 * 1024,
151
+ keepPdf: false,
152
+ pdfPageMaxChars: 4000,
153
+ },
154
+ image: { attachMaxBytes: 8 * 1024 * 1024 },
155
+ cache: { serpTtlMs: 600000, gotoTtlMs: 86400000, maxEntries: 200 },
156
+ artifacts: { enabled: true, keep: 30, maxBytes: 52428800 },
157
+ debug: false,
158
+ };
@@ -0,0 +1,180 @@
1
+ /**
2
+ * Documentation data for `docs/config.md` (S13.3).
3
+ *
4
+ * The generator walks `CONFIG_SPEC` and `DEFAULT_CONFIG`, so a key, default,
5
+ * range or enum member cannot drift from this page. Every leaf must have a
6
+ * meaning here; a missing entry fails generation instead of shipping a blank.
7
+ */
8
+
9
+ import { DEFAULT_CONFIG } from "./defaults.ts";
10
+ import { ENV_OVERRIDES } from "./env.ts";
11
+ import { CONFIG_SPEC, type Spec } from "./schema.ts";
12
+
13
+ const CONFIG_DOCS: Readonly<Record<string, string>> = {
14
+ "cdp.ports": "Ports probed when no `DevToolsActivePort` and no env URL exists.",
15
+ "cdp.ws": "Explicit WebSocket URL; `null` means discover.",
16
+ "cdp.connectTimeoutMs": "Per-attempt connect budget.",
17
+ "cdp.attachWaitMs": "How long to wait for the CDP Allow click before `E_CDP_AWAITING_ALLOW`; `0` disables the wait.",
18
+ "window.focus": "`session` raises on the first search, `always` on every stage, `never` never.",
19
+ "window.raiseOnPrompt": "Best-effort raise while the Allow prompt waits; `never` keeps the session passive.",
20
+ "window.panel": "Host the local anchor control panel (`assets/anchor.html`).",
21
+ "window.follow": "`work` raises the work tab, `anchor` the panel tab, `never` nothing.",
22
+ "window.idleMs": "Delay before the anchor returns after a stage ends.",
23
+ humanize: "`auto` types the first search per session, `always` every search, `typing` uses per-engine profiles.",
24
+ "engines.google.enabled": "Use Google.",
25
+ "engines.google.lang": "`hl`; `auto` omits it.",
26
+ "engines.google.gl": "`gl`; `auto` omits it.",
27
+ "engines.duckduckgo.enabled": "Use DuckDuckGo.",
28
+ "engines.duckduckgo.kl": "Region/language; `auto` omits it.",
29
+ "engines.yandex.enabled": "Use Yandex.",
30
+ "engines.yandex.lr": "`lr`; `auto` omits it.",
31
+ "pacing.google": "Min/max gap in ms between Google searches.",
32
+ "pacing.duckduckgo": "Min/max gap in ms between DuckDuckGo searches.",
33
+ "pacing.yandex": "Min/max gap in ms between Yandex searches.",
34
+ "search.budgetMs": "Whole-call deadline in ms; pacing, settle, AI wait and link resolution draw from it (S8.1).",
35
+ "search.n": "Default result count.",
36
+ "search.nMax": "Hard ceiling for `n`; never above 10.",
37
+ "search.summaryMaxChars": "Cap for the AI answer block.",
38
+ "search.snippetMaxChars": "Cap for one snippet.",
39
+ "search.outputMaxChars": "Cap for the whole Markdown output.",
40
+ "search.aiWaitMs": "Deadline for the native AI block; `0` disables waiting.",
41
+ "search.aiExpand": "Click the engine's \"show more\" on the AI card once.",
42
+ "read.budgetMs": "Whole-call deadline in ms; navigation, readiness, extraction and the PDF ladder draw from it (S8.1).",
43
+ "read.defaultMaxChars": "Default `maxChars` window.",
44
+ "read.maxCharsCeiling": "`maxChars` above this is clamped and reported.",
45
+ "read.pool": "Concurrent read slots; each holds its own tab and exclusive lock.",
46
+ "read.pdfMaxBytes": "Refuse larger PDFs.",
47
+ "read.keepPdf": "Keep the downloaded PDF in the artifact directory.",
48
+ "read.pdfPageMaxChars": "Per-page cap for PDF text.",
49
+ "image.attachMaxBytes": "Size ceiling for one attached image.",
50
+ "cache.serpTtlMs": "SERP cache TTL (10 min).",
51
+ "cache.gotoTtlMs": "Resolved `/goto` links TTL (24 h).",
52
+ "cache.maxEntries": "LRU size.",
53
+ "artifacts.enabled": "Write `page.html`/`page.txt`/`screenshot.jpg`/`meta.json` on failures.",
54
+ "artifacts.keep": "Artifact directories to keep.",
55
+ "artifacts.maxBytes": "Artifact root budget.",
56
+ debug: "Verbose decision logging.",
57
+ };
58
+
59
+ export interface ConfigDocRow {
60
+ path: string;
61
+ defaultValue: string;
62
+ constraint: string;
63
+ meaning: string;
64
+ }
65
+
66
+ function isRecord(value: unknown): value is Record<string, unknown> {
67
+ return typeof value === "object" && value !== null && !Array.isArray(value);
68
+ }
69
+
70
+ function formatDefault(value: unknown): string {
71
+ return JSON.stringify(value);
72
+ }
73
+
74
+ function constraint(spec: Spec): string {
75
+ switch (spec.kind) {
76
+ case "string":
77
+ return spec.nonEmpty ? "non-empty string" : "string";
78
+ case "enum":
79
+ return `one of ${spec.values.map((value) => `\`${value}\``).join(", ")}`;
80
+ case "number": {
81
+ const type = spec.integer ? "integer" : "number";
82
+ if (spec.min !== undefined && spec.max !== undefined) return `${type} ${spec.min}..${spec.max}`;
83
+ if (spec.min !== undefined) return `${type} ≥ ${spec.min}`;
84
+ if (spec.max !== undefined) return `${type} ≤ ${spec.max}`;
85
+ return type;
86
+ }
87
+ case "boolean":
88
+ return "boolean";
89
+ case "null":
90
+ return "null";
91
+ case "nullable":
92
+ return `null or ${constraint(spec.of)}`;
93
+ case "array": {
94
+ const item = constraint(spec.item);
95
+ const count =
96
+ spec.minItems !== undefined && spec.maxItems !== undefined
97
+ ? ` (${spec.minItems}..${spec.maxItems} items)`
98
+ : spec.minItems !== undefined
99
+ ? ` (≥${spec.minItems} items)`
100
+ : "";
101
+ return `array of ${item}${count}`;
102
+ }
103
+ case "tuple":
104
+ return `[${spec.items.map(constraint).join(", ")}]`;
105
+ case "object":
106
+ return "object";
107
+ }
108
+ }
109
+
110
+ function valueAt(path: string): unknown {
111
+ let current: unknown = DEFAULT_CONFIG;
112
+ for (const segment of path.split(".")) {
113
+ if (!isRecord(current)) throw new Error(`config default is missing ${path}`);
114
+ current = current[segment];
115
+ }
116
+ return current;
117
+ }
118
+
119
+ function walk(spec: Spec, prefix: string, rows: ConfigDocRow[]): void {
120
+ if (spec.kind === "object") {
121
+ for (const [key, field] of Object.entries(spec.fields)) {
122
+ walk(field, prefix === "" ? key : `${prefix}.${key}`, rows);
123
+ }
124
+ return;
125
+ }
126
+ const meaning = CONFIG_DOCS[prefix];
127
+ if (meaning === undefined) throw new Error(`docs/config.md: no meaning for ${prefix}`);
128
+ const value = valueAt(prefix);
129
+ if (value === undefined) throw new Error(`docs/config.md: no default for ${prefix}`);
130
+ rows.push({
131
+ path: prefix,
132
+ defaultValue: formatDefault(value),
133
+ constraint: constraint(spec),
134
+ meaning,
135
+ });
136
+ }
137
+
138
+ export function configDocRows(): ConfigDocRow[] {
139
+ const rows: ConfigDocRow[] = [];
140
+ walk(CONFIG_SPEC, "", rows);
141
+ const documented = new Set(Object.keys(CONFIG_DOCS));
142
+ for (const row of rows) documented.delete(row.path);
143
+ if (documented.size > 0) {
144
+ throw new Error(`docs/config.md: stale meanings for ${[...documented].join(", ")}`);
145
+ }
146
+ return rows;
147
+ }
148
+
149
+ export function renderConfigDoc(): string {
150
+ const rows = configDocRows();
151
+ const env = ENV_OVERRIDES.map((entry) => `| \`${entry.name}\` | ${entry.effect} |`);
152
+ return [
153
+ "# Configuration",
154
+ "",
155
+ "Generated from `src/config/{defaults,schema,env}.ts`; do not hand-edit. `node scripts/gen-config-doc.mjs",
156
+ "--check` fails when this page drifts from the schema.",
157
+ "",
158
+ "Path: `~/.pi/agent/web-search.json` (or `$PI_CODING_AGENT_DIR/web-search.json`). Optional: the defaults",
159
+ "below are complete. Parsing is strict: an unknown key, wrong type or out-of-range value is `E_CONFIG`",
160
+ "naming the dotted path.",
161
+ "",
162
+ "## Environment overrides (applied after the file)",
163
+ "",
164
+ "| Variable | Effect |",
165
+ "|---|---|",
166
+ ...env,
167
+ "",
168
+ "## Keys and defaults",
169
+ "",
170
+ "| Key | Default | Constraint | Meaning |",
171
+ "|---|---|---|---|",
172
+ ...rows.map(
173
+ (row) => `| \`${row.path}\` | \`${row.defaultValue}\` | ${row.constraint} | ${row.meaning} |`,
174
+ ),
175
+ "",
176
+ "Cross-field rules: `search.n ≤ search.nMax ≤ 10`, `read.defaultMaxChars ≤ read.maxCharsCeiling`,",
177
+ "`pacing.*[0] ≤ pacing.*[1]`, and at least one engine enabled.",
178
+ "",
179
+ ].join("\n");
180
+ }