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.
- package/README.md +37 -76
- package/assets/anchor.html +2 -2
- package/package.json +4 -1
- package/src/cdp/bytes.ts +14 -14
- package/src/cdp/client.ts +687 -0
- package/src/cdp/page.ts +716 -0
- package/src/cdp/readiness.ts +119 -0
- package/src/cdp/shared.ts +70 -0
- package/src/cdp/types.ts +30 -1
- package/src/cli/doctor.ts +14 -17
- package/src/commands/focus.ts +2 -2
- package/src/config/defaults.ts +158 -0
- package/src/config/doc.ts +180 -0
- package/src/config/env.ts +58 -0
- package/src/config/index.ts +10 -0
- package/src/config/load.ts +40 -0
- package/src/config/schema.ts +264 -0
- package/src/engines/duckduckgo.ts +7 -10
- package/src/engines/google.ts +11 -21
- package/src/engines/images.ts +1 -1
- package/src/engines/index.ts +5 -13
- package/src/engines/types.ts +29 -6
- package/src/engines/yandex.ts +11 -18
- package/src/extract/claims.ts +1 -1
- package/src/extract/compact.ts +29 -3
- package/src/extract/goto.ts +124 -2
- package/src/extract/text.ts +43 -0
- package/src/index.ts +52 -80
- package/src/runtime/artifacts.ts +6 -11
- package/src/runtime/attention.ts +2 -2
- package/src/runtime/budget.ts +142 -0
- package/src/runtime/cache.ts +1 -3
- package/src/runtime/doctor.ts +17 -43
- package/src/runtime/error-codes.ts +19 -8
- package/src/runtime/errors-doc.ts +45 -0
- package/src/runtime/limiter.ts +33 -221
- package/src/runtime/log.ts +2 -2
- package/src/runtime/panel.ts +30 -4
- package/src/runtime/types.ts +2 -17
- package/src/{cdp/discovery.ts → session/discover.ts} +3 -3
- package/src/session/index.ts +34 -0
- package/src/session/lock.ts +346 -0
- package/src/{cdp → session}/page-lock.ts +12 -13
- package/src/session/session.ts +684 -0
- package/src/session/tabs.ts +277 -0
- package/src/tools/image_search.ts +21 -7
- package/src/tools/index.ts +18 -7
- package/src/tools/surface.ts +97 -0
- package/src/tools/types.ts +2 -5
- package/src/tools/web_doctor.ts +2 -2
- package/src/tools/web_read.ts +159 -114
- package/src/tools/web_research.ts +33 -207
- package/src/tools/web_search.ts +208 -419
- package/src/version.ts +12 -3
- package/src/cdp/browser.ts +0 -1286
- package/src/cdp/session.ts +0 -1446
- package/src/config.ts +0 -651
- package/src/reflex/classifier.ts +0 -1578
- package/src/reflex/index.ts +0 -172
- package/src/reflex/policy.ts +0 -792
- package/src/reflex/rules.ts +0 -557
- 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
|
|
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 `
|
|
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 {
|
|
33
|
-
import type {
|
|
34
|
-
import {
|
|
35
|
-
import {
|
|
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?:
|
|
87
|
-
|
|
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
|
|
95
|
-
*
|
|
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:
|
|
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.
|
|
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
|
|
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:
|
|
386
|
+
async function releaseQuietly(connector: Session): Promise<void> {
|
|
390
387
|
try {
|
|
391
388
|
if (connector.isConnected()) await connector.releaseAll();
|
|
392
389
|
} catch {
|
package/src/commands/focus.ts
CHANGED
|
@@ -8,12 +8,12 @@
|
|
|
8
8
|
* that is the one case where focusing opens something.
|
|
9
9
|
*/
|
|
10
10
|
|
|
11
|
-
import type {
|
|
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?:
|
|
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
|
+
}
|