@parcha/pi-browser 0.1.0-beta.34 → 0.1.0-beta.36

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 (54) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/README.md +23 -44
  3. package/dist/core/contract.d.ts +9 -6
  4. package/dist/core/contract.js +8 -29
  5. package/dist/core/driving-guard.d.ts +1 -1
  6. package/dist/core/driving-guard.js +1 -1
  7. package/dist/core/evidence.d.ts +1 -1
  8. package/dist/core/files.d.ts +3 -0
  9. package/dist/core/files.js +4 -1
  10. package/dist/core/host.d.ts +1 -75
  11. package/dist/core/images.d.ts +32 -4
  12. package/dist/core/images.js +81 -16
  13. package/dist/core/redact.d.ts +0 -2
  14. package/dist/core/redact.js +0 -32
  15. package/dist/core/session-control.d.ts +0 -2
  16. package/dist/core/session-control.js +0 -5
  17. package/dist/core/tools.js +4 -1
  18. package/dist/core/usage.d.ts +0 -2
  19. package/dist/core/usage.js +0 -2
  20. package/dist/core/vault.d.ts +0 -10
  21. package/dist/core/vault.js +0 -13
  22. package/dist/core/web.d.ts +2 -111
  23. package/dist/core/web.js +0 -443
  24. package/dist/driver/cdp.js +3 -3
  25. package/dist/driver/page-driver.js +7 -3
  26. package/dist/durable.d.ts +6 -12
  27. package/dist/durable.js +31 -84
  28. package/dist/index.d.ts +1 -1
  29. package/dist/index.js +3 -1
  30. package/dist/providers/cdp.js +2 -2
  31. package/dist/providers/profiles.d.ts +1 -15
  32. package/dist/providers/profiles.js +1 -64
  33. package/dist/providers/shared.d.ts +1 -47
  34. package/dist/providers/shared.js +1 -82
  35. package/dist/providers/worker-extension.js +1 -1
  36. package/dist/testing/backend.d.ts +6 -24
  37. package/dist/testing/backend.js +7 -30
  38. package/dist/vault-session.d.ts +4 -7
  39. package/dist/vault-session.js +26 -81
  40. package/dist/vendor/browser-use-pi/page.d.ts +3 -12
  41. package/dist/vendor/browser-use-pi/page.js +6 -19
  42. package/package.json +3 -16
  43. package/dist/core/sites.d.ts +0 -33
  44. package/dist/core/sites.js +0 -104
  45. package/dist/durable/web.d.ts +0 -47
  46. package/dist/durable/web.js +0 -41
  47. package/dist/providers/browserbase-net.d.ts +0 -12
  48. package/dist/providers/browserbase-net.js +0 -95
  49. package/dist/providers/browserbase.d.ts +0 -169
  50. package/dist/providers/browserbase.js +0 -319
  51. package/dist/providers/kernel.d.ts +0 -58
  52. package/dist/providers/kernel.js +0 -291
  53. /package/dist/{providers → core}/cdp-call.d.ts +0 -0
  54. /package/dist/{providers → core}/cdp-call.js +0 -0
@@ -1,7 +1,11 @@
1
1
  // Tool images are stored verbatim and resent on every later request, and routes reject oversize ones: a capture is held
2
- // to a long edge and a base64 size.
2
+ // to a long edge and a base64 size, by shrinking its pixels and then its JPEG quality, never by failing while a capture
3
+ // can be made.
3
4
  export const SCREENSHOT_MAX_EDGE_PX = 2_000;
4
5
  export const SCREENSHOT_MAX_BASE64_BYTES = 900_000;
6
+ /** A full page shrunk to the long edge that would be narrower than this (its short edge) is unreadable: the viewport is
7
+ * taken in its place. */
8
+ export const SCREENSHOT_MIN_SHORT_EDGE_PX = 600;
5
9
  const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
6
10
  /** JPEG start-of-frame markers; C4 (DHT), C8 (JPG) and CC (DAC) are not frames. */
7
11
  const JPEG_SOF = new Set([0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf]);
@@ -34,27 +38,88 @@ export function imageSize(bytes) {
34
38
  }
35
39
  return null;
36
40
  }
41
+ /** CDP's Page.captureScreenshot parameters for `options` on a page laid out as `layout`. Chrome scales a clip alone, its
42
+ * image `clip.scale` times its device pixels: a clip (from the viewport) is moved to the document, a full page is the
43
+ * document's clip captured beyond the viewport, and a scaled viewport is the viewport's own clip. */
44
+ export function captureParams(options, layout) {
45
+ const format = options.type ?? "png";
46
+ const scale = options.scale ?? 1;
47
+ const view = layout.cssVisualViewport;
48
+ const region = options.clip ? { ...options.clip, x: options.clip.x + view.pageX, y: options.clip.y + view.pageY }
49
+ : options.fullPage ? { x: 0, y: 0, width: Math.ceil(layout.cssContentSize.width), height: Math.ceil(layout.cssContentSize.height) }
50
+ : scale !== 1 ? { x: view.pageX, y: view.pageY, width: view.clientWidth, height: view.clientHeight }
51
+ : null;
52
+ return {
53
+ format,
54
+ // CDP takes a quality for jpeg only, and only as an integer.
55
+ ...(format === "jpeg" && options.quality !== undefined ? { quality: Math.round(options.quality) } : {}),
56
+ ...(options.fullPage && !options.clip ? { captureBeyondViewport: true } : {}),
57
+ ...(region ? { clip: { ...region, scale } } : {}),
58
+ };
59
+ }
37
60
  export class ScreenshotBudgetError extends Error {
38
61
  name = "ScreenshotBudgetError";
39
62
  }
40
- /** Over budget, retakes as a viewport JPEG at CSS scale, quality 40, 25, 10 (of the same clip, when there is one); throws ScreenshotBudgetError. */
63
+ /** The most captures one screenshot takes before it gives up. */
64
+ const MAX_CAPTURES = 12;
65
+ const QUALITIES = [40, 25, 10];
66
+ /**
67
+ * A capture as requested, held to the budget. Over the long edge, the same region is retaken scaled to fit it (a full
68
+ * page that would come out narrower than SCREENSHOT_MIN_SHORT_EDGE_PX is the viewport instead, itself scaled to fit);
69
+ * over the byte budget, as a JPEG at quality 40, 25 and 10 (at most the requested quality), then smaller still. A capture
70
+ * whose size cannot be read is retaken once as a viewport JPEG. Throws ScreenshotBudgetError only when no capture it can
71
+ * measure is made, or none fits within MAX_CAPTURES.
72
+ */
41
73
  export async function captureWithinBudget(capture, requested, budget = { maxEdgePx: SCREENSHOT_MAX_EDGE_PX, maxBase64Bytes: SCREENSHOT_MAX_BASE64_BYTES }) {
42
74
  const ceiling = requested.type === "png" ? 40 : (requested.quality ?? 40);
43
- const ladder = [
44
- { fullPage: requested.fullPage ?? false, type: requested.type ?? "jpeg", ...(requested.type === "png" ? {} : { quality: requested.quality ?? 40 }), ...(requested.scale ? { scale: requested.scale } : {}), ...(requested.clip ? { clip: requested.clip } : {}) },
45
- ...[40, 25, 10].map((quality) => ({ fullPage: false, type: "jpeg", quality: Math.min(ceiling, quality), scale: "css", ...(requested.clip ? { clip: requested.clip } : {}) })),
46
- ];
47
- const key = (o) => `${o.fullPage}:${o.type}:${o.quality}:${o.scale}:${o.clip ? `${o.clip.x},${o.clip.y},${o.clip.width},${o.clip.height}` : ""}`;
48
- const attempts = ladder.filter((o, i) => ladder.findIndex((other) => key(other) === key(o)) === i);
49
- let adjusted = null;
50
- for (const options of attempts) {
75
+ // The clip and the scale asked are kept on every capture; a retake only scales further down.
76
+ const clip = { ...(requested.clip ? { clip: requested.clip } : {}), ...(requested.scale === undefined ? {} : { scale: requested.scale }) };
77
+ let taken = 0;
78
+ const take = async (options) => {
79
+ taken += 1;
51
80
  const image = await capture(options);
52
81
  const size = imageSize(Buffer.from(image.data, "base64"));
53
- const why = size === null || Math.max(size.width, size.height) > budget.maxEdgePx ? "long_edge"
54
- : Buffer.byteLength(image.data, "utf8") > budget.maxBase64Bytes ? "base64_bytes" : null;
55
- if (why === null && size)
56
- return { data: image.data, mimeType: image.mimeType, size, options, adjusted };
57
- adjusted ??= { why: why ?? "long_edge", first: size };
82
+ const why = size === null ? "unreadable"
83
+ : Math.max(size.width, size.height) > budget.maxEdgePx ? "long_edge"
84
+ : Buffer.byteLength(image.data, "utf8") > budget.maxBase64Bytes ? "base64_bytes" : null;
85
+ return { image, size, why, options };
86
+ };
87
+ const fit = (size) => budget.maxEdgePx / Math.max(size.width, size.height);
88
+ const viewport = (options) => ({ fullPage: false, type: "jpeg", quality: Math.min(ceiling, options.type === "jpeg" ? options.quality ?? 40 : 40), ...clip });
89
+ let shot = await take({ fullPage: requested.fullPage ?? false, type: requested.type ?? "jpeg", ...(requested.type === "png" ? {} : { quality: ceiling }), ...clip });
90
+ const adjusted = shot.why === null ? null : { why: shot.why, first: shot.size };
91
+ if (shot.why === "unreadable")
92
+ shot = await take(viewport(shot.options));
93
+ // A full page that fits only narrower than a page can be read: the viewport, which the steps below fit.
94
+ if (shot.why === "long_edge" && shot.options.fullPage && shot.size && Math.min(shot.size.width, shot.size.height) * fit(shot.size) < SCREENSHOT_MIN_SHORT_EDGE_PX) {
95
+ shot = await take(viewport(shot.options));
96
+ }
97
+ while (shot.why !== null) {
98
+ if (shot.why === "unreadable" || !shot.size)
99
+ throw new ScreenshotBudgetError("The browser's capture is not a PNG or JPEG whose size can be read, and a viewport JPEG retake is not either.");
100
+ if (taken >= MAX_CAPTURES)
101
+ throw new ScreenshotBudgetError(`No capture fits ${budget.maxEdgePx} px on its long edge and ${budget.maxBase64Bytes} base64 bytes after ${taken} captures; the last was ${shot.size.width}x${shot.size.height}.`);
102
+ const { options, size } = shot;
103
+ const scale = options.scale ?? 1;
104
+ let next;
105
+ if (shot.why === "long_edge") {
106
+ next = { ...options, scale: scale * fit(size) };
107
+ }
108
+ else {
109
+ const quality = options.type === "png" ? undefined : options.quality ?? 40;
110
+ const lower = QUALITIES.map((q) => Math.min(ceiling, q)).find((q) => quality === undefined || q < quality);
111
+ // Its bytes go roughly with its area: a scale that takes them to nine tenths of the budget.
112
+ const smaller = scale * Math.min(0.9, 0.9 * Math.sqrt(budget.maxBase64Bytes / Buffer.byteLength(shot.image.data, "utf8")));
113
+ next = lower !== undefined ? { ...options, type: "jpeg", quality: lower } : { ...options, scale: smaller };
114
+ }
115
+ shot = await take(next);
116
+ // A driver that does not take the scale asked (Stagehand's, past one image pixel per CSS pixel): a full page is the
117
+ // viewport instead, and anything else is as small as this browser makes it.
118
+ if ((next.scale ?? 1) < scale && shot.size && Math.max(shot.size.width, shot.size.height) >= Math.max(size.width, size.height)) {
119
+ if (!options.fullPage)
120
+ throw new ScreenshotBudgetError(`The browser does not take this capture smaller than ${shot.size.width}x${shot.size.height}, which is over ${budget.maxEdgePx} px on its long edge or ${budget.maxBase64Bytes} base64 bytes.`);
121
+ shot = await take(viewport(options));
122
+ }
58
123
  }
59
- throw new ScreenshotBudgetError(`The screenshot stays over ${budget.maxEdgePx} px on its long edge or ${budget.maxBase64Bytes} base64 bytes after viewport JPEG retakes at CSS scale and quality 40, 25 and 10.`);
124
+ return { data: shot.image.data, mimeType: shot.image.mimeType, size: shot.size, options: shot.options, adjusted };
60
125
  }
@@ -16,7 +16,5 @@ export declare function redactContent<T extends {
16
16
  /** A live view as the host receives it, on every channel (`onSession`, a handoff's `request`): the viewer's own URLs stay
17
17
  * whole, since the host needs their token; a browsed page's URL and title are scrubbed, since its query can carry a credential. */
18
18
  export declare function hostLiveView(view: LiveView, redact: Redact): LiveView;
19
- /** A fetch's final URL for the model: a query value or fragment stays only where the requested URL has it; userinfo never does. */
20
- export declare function scrubFetchedUrl(raw: string, requested: string, redact: Redact): string;
21
19
  /** Every string inside `value`, object keys included, passed through `redact`. */
22
20
  export declare function redactDeep<T>(value: T, redact: Redact): T;
@@ -47,38 +47,6 @@ export function redactContent(content, redact) {
47
47
  export function hostLiveView(view, redact) {
48
48
  return { ...view, pages: view.pages.map((page) => ({ ...page, url: page.url === null ? null : scrubPageUrl(page.url, redact), title: page.title === null ? null : redact(page.title) })) };
49
49
  }
50
- /** A fetch's final URL for the model: a query value or fragment stays only where the requested URL has it; userinfo never does. */
51
- export function scrubFetchedUrl(raw, requested, redact) {
52
- let url, asked;
53
- try {
54
- url = new URL(raw);
55
- }
56
- catch {
57
- return redact(raw);
58
- }
59
- if (url.protocol !== "http:" && url.protocol !== "https:")
60
- return redact(raw);
61
- try {
62
- asked = new URL(requested);
63
- }
64
- catch {
65
- return scrubPageUrl(raw, redact);
66
- }
67
- const decoded = (text) => { try {
68
- return decodeURIComponent(text.replace(/\+/g, " "));
69
- }
70
- catch {
71
- return text;
72
- } };
73
- const pairsOf = (search) => search.slice(1).split("&").filter(Boolean).map((pair) => {
74
- const at = pair.indexOf("=");
75
- return at < 0 ? { pair, key: pair, value: "" } : { pair, key: pair.slice(0, at), value: pair.slice(at + 1) };
76
- });
77
- const sent = new Set(pairsOf(asked.search).map(({ key, value }) => `${decoded(key)}\0${decoded(value)}`));
78
- const query = pairsOf(url.search).map(({ pair, key, value }) => (sent.has(`${decoded(key)}\0${decoded(value)}`) ? pair : `${key}=${REDACTED}`));
79
- const fragment = url.hash && url.hash === asked.hash ? url.hash : "";
80
- return redact(`${url.protocol}//${url.host}${url.pathname}${query.length ? `?${query.join("&")}` : ""}${fragment}`);
81
- }
82
50
  /** Every string inside `value`, object keys included, passed through `redact`. */
83
51
  export function redactDeep(value, redact) {
84
52
  if (typeof value === "string")
@@ -23,5 +23,3 @@ export declare function idleTracker<K = string>(options: {
23
23
  /** Every environment variable that holds a provider key: each redactor in either adapter scrubs their values. */
24
24
  export declare const PROVIDER_KEY_ENV: readonly string[];
25
25
  export declare const providerKeyValues: (env: NodeJS.ProcessEnv, host?: () => readonly string[]) => string[];
26
- /** Runs one at a time, in arrival order: each starts once the one before it has settled, however that one ended. */
27
- export declare function oneAtATime(): <T>(run: () => Promise<T>) => Promise<T>;
@@ -73,8 +73,3 @@ export function idleTracker(options) {
73
73
  /** Every environment variable that holds a provider key: each redactor in either adapter scrubs their values. */
74
74
  export const PROVIDER_KEY_ENV = Object.freeze(["BROWSERBASE_API_KEY", "BB_API_KEY", "KERNEL_API_KEY"]);
75
75
  export const providerKeyValues = (env, host) => [...PROVIDER_KEY_ENV.map((name) => env[name] ?? "").filter(Boolean), ...(host?.() ?? [])];
76
- /** Runs one at a time, in arrival order: each starts once the one before it has settled, however that one ended. */
77
- export function oneAtATime() {
78
- let turn = Promise.resolve();
79
- return (run) => { const mine = turn.then(run, run); turn = mine.catch(() => undefined); return mine; };
80
- }
@@ -421,7 +421,10 @@ export function pageTools({ guards = new Map(), reconnect: timings = RECONNECT,
421
421
  const url = pageUrl(call, await s.driver.url());
422
422
  const receipt = await file(s, call, { tool: "screenshot", args: region ? { ...requested, clip: region.clip, ...region.of } : requested, status: "ok", facts: { final_url: url }, body: Buffer.from(shot.data, "base64"), ext: shot.size.type === "png" ? "png" : "jpg" });
423
423
  const first = shot.adjusted?.first;
424
- const adjusted = shot.adjusted && `adjusted: the first capture${first ? ` (${first.width}x${first.height})` : ""} was over the ${shot.adjusted.why === "long_edge" ? "2,000 px long edge" : "size"} budget; this is ${region ? "the clip" : "the viewport"} at ${shot.size.width}x${shot.size.height}`;
424
+ const over = shot.adjusted?.why === "long_edge" ? "was over the 2,000 px long edge budget" : shot.adjusted?.why === "base64_bytes" ? "was over the size budget" : "could not be measured";
425
+ const taken = shot.options.clip ? "the clip" : shot.options.fullPage ? "the full page" : "the viewport";
426
+ const scaled = shot.options.scale !== undefined && shot.options.scale < 1 ? ", scaled down" : "";
427
+ const adjusted = shot.adjusted && `adjusted: the first capture${first ? ` (${first.width}x${first.height})` : ""} ${over}; this is ${taken} at ${shot.size.width}x${shot.size.height}${scaled}`;
425
428
  const lines = [news, `url: ${url}`, `evidence: ${receipt.path ?? "(not filed)"}`, adjusted].filter(Boolean).join("\n");
426
429
  const media = { kind: "screenshot", path: receipt.bodyPath, mime: shot.mimeType, bytes: Buffer.from(shot.data, "base64").byteLength, width: shot.size.width, height: shot.size.height, ...(region ? { clip: region.clip, ...region.of } : {}), ...(ask ? { ask } : {}) };
427
430
  return { content: [{ type: "text", text: lines }, { type: "image", data: shot.data, mimeType: shot.mimeType }], details: { evidence: receipt.path, sha256: receipt.sha256, media } };
@@ -7,8 +7,6 @@ export declare function sessionPrice(raw: string | null | undefined): {
7
7
  /** List prices with the host's overrides on top; an override of `null` is a deliberate gap. */
8
8
  export declare const resolvePrices: (overrides?: Partial<PriceTable>) => PriceTable;
9
9
  export declare const toolUsage: (usd: number, state?: PriceState) => ToolUsage;
10
- export declare const fetchUsage: (prices: PriceTable, proxied: boolean) => ToolUsage;
11
- export declare const searchUsage: (prices: PriceTable) => ToolUsage;
12
10
  type Spent = SessionRecord["spent"];
13
11
  export declare const startSpent: (createdAt: string) => Spent;
14
12
  /** The record after a charge, with its list-priced dollars: the ones it already held plus this charge's when the price was the list's. `after` is what `sessionCharge` returned. */
@@ -17,8 +17,6 @@ export const toolUsage = (usd, state = "priced") => ({
17
17
  usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: usd } },
18
18
  state,
19
19
  });
20
- export const fetchUsage = (prices, proxied) => toolUsage(proxied ? prices.fetchProxiedUsd : prices.fetchUsd);
21
- export const searchUsage = (prices) => toolUsage(prices.searchUsd);
22
20
  /** Integer picodollars, so a bill reads as its decimal amount (0.002, not 0.0019999999999999996). */
23
21
  const PICO = 1e12;
24
22
  const HOUR_MS = 3600000n;
@@ -19,17 +19,7 @@ export type CapturedState = {
19
19
  /** Only cookies the allowed origins would be sent (see `cookieKept`). Partitioned cookies are not kept. */
20
20
  cookies: VaultCookie[];
21
21
  localStorage: Record<string, Record<string, string>>;
22
- }
23
- /** `origins`: the origins the context was captured for. A context holds a whole browser profile, so it is restored only for a request that covers EVERY one of them (`coversEveryOrigin`); one that records none is refused. */
24
- | {
25
- kind: "provider-context";
26
- capturedAt: string;
27
- provider: "browserbase" | "kernel";
28
- contextId: string;
29
- origins?: string[];
30
22
  };
31
- /** Whether `requested` includes every origin in `saved` (as scheme://host[:port], any order): a provider context is all-or-nothing, so a request for some of its origins would bring back the others' sign-ins. */
32
- export declare function coversEveryOrigin(requested: readonly string[], saved: readonly string[] | undefined): boolean;
33
23
  export interface SessionVaultPort {
34
24
  /** At release and at the end of a handoff, and, for a context a new session made, right after the create (so a restart still finds it). The host supplied the origins; nothing outside them was captured.
35
25
  * A capture has a deadline (20 s) after which nothing more is read or written, but a write already handed to this port cannot be recalled: ignore one whose `capturedAt` is older than the one you hold. */
@@ -11,19 +11,6 @@ export function clampSessionCookieAgeMs(requested) {
11
11
  throw new RangeError("the session-cookie age cap is a positive number of milliseconds");
12
12
  return Math.min(requested, MAX_SESSION_COOKIE_AGE_MS);
13
13
  }
14
- /** Whether `requested` includes every origin in `saved` (as scheme://host[:port], any order): a provider context is all-or-nothing, so a request for some of its origins would bring back the others' sign-ins. */
15
- export function coversEveryOrigin(requested, saved) {
16
- if (!saved || saved.length === 0)
17
- return false;
18
- const origin = (value) => { try {
19
- return new URL(value).origin;
20
- }
21
- catch {
22
- return null;
23
- } };
24
- const have = new Set(requested.map(origin));
25
- return saved.every((value) => { const o = origin(value); return o !== null && have.has(o); });
26
- }
27
14
  const SESSION_KEY = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/;
28
15
  /** The host's allowed origins, each `scheme://host[:port]` of http or https, normalised and de-duplicated; anything else is refused. */
29
16
  export function vaultOrigins(origins) {
@@ -1,107 +1,10 @@
1
- import type { Decisions, PageVerdict, WallClass } from "./decisions.js";
2
- import { type EvidenceSink } from "./evidence.js";
3
- import { type BrowserFailure, type Next } from "./failures.js";
4
- import { type FetchRequest, type FetchResult, type PriceTable, type SearchRequest, type SearchResult } from "./host.js";
5
- export declare const WEB_SEARCH_QUERY_MAX = 200;
6
- export declare const WEB_SEARCH_RESULTS_MAX = 25;
7
- export declare const WEB_SEARCH_RESULTS_DEFAULT = 10;
8
- /** A provider's excerpt with markdown links reduced to their text and whitespace collapsed, clipped at a word boundary;
9
- * null when it has no text. A link inside a page is the page's lead, not the hit's, and its URL only spends the bound. */
10
- export declare function boundSnippet(raw: unknown): string | null;
1
+ import type { PageVerdict, WallClass } from "./decisions.js";
2
+ import type { BrowserFailure, Next } from "./failures.js";
11
3
  /** Over 507 recorded pages, ordinary pages scored up to 0.66 and a page with a spliced instruction 0.98. */
12
4
  export declare const INJECTION_THRESHOLD = 0.75;
13
- /** A search answer's snippets are page text the model has not read through a fetch, so each hit that carries one is judged like a page
14
- * before the model sees it. At most this many judgments run at once, and the whole screen is held to this long. */
15
- export declare const SNIPPET_SCREEN_CONCURRENCY = 5;
16
- export declare const SNIPPET_SCREEN_TIMEOUT_MS = 30000;
17
- /** The largest PDF handed to the host's `pdf.text`; a larger one is named and left to `format: "raw"`. */
18
- export declare const PDF_TEXT_MAX_BYTES: number;
19
- export declare const PDF_TEXT_TIMEOUT_MS = 120000;
20
- /** Told the calling conversation's scope, so a host can hold it to what that conversation may use. `available`, when
21
- * given, says whether that conversation can reach it at all: a backup it answers false for is neither tried nor named
22
- * among the sources tried. */
23
- export type WebBackup = {
24
- name: string;
25
- available?(scope: {
26
- label: string;
27
- proxies: boolean;
28
- }): boolean;
29
- fetch(url: string, signal?: AbortSignal, scope?: {
30
- label: string;
31
- proxies: boolean;
32
- }): Promise<string>;
33
- };
34
- /** A search the host tries before the provider's own, in order: one that throws hands the call to the next, and the
35
- * provider's own search answers last. Its answer is priced at the usage it reports, else at the list search price.
36
- * `available`, when given, is asked at each call: a source it answers false for is neither tried nor named as a
37
- * failure (one that has learned it is not served this run). */
38
- export type SearchSource = {
39
- name: string;
40
- available?(): boolean;
41
- search(request: SearchRequest, signal?: AbortSignal): Promise<SearchResult>;
42
- };
43
- /** A reader the host tries before the provider's own fetch for a markdown read, in order, with `available` as for a
44
- * `SearchSource`. One that throws, or answers no content or an HTTP error status, hands the call to the next; its
45
- * failure is never the call's own, which stays the provider's. A page it answers is filed exactly as the provider's
46
- * is, under `via: <name>_fetch`, and is priced at the usage it reports, else at the list fetch price. */
47
- export type FetchSource = {
48
- name: string;
49
- available?(): boolean;
50
- fetch(request: FetchRequest, signal?: AbortSignal): Promise<FetchResult>;
51
- };
52
- export type RenderedPage = {
53
- finalUrl: string | null;
54
- statusCode: number | null;
55
- contentType: string | null;
56
- content: string;
57
- extractor?: "readability-md" | "inner-text";
58
- usd?: number;
59
- };
60
- export type WebToolsOptions = {
61
- /** `via` is `<name>_fetch` and `<name>_search`. */
62
- name: string;
63
- fetch?: (request: FetchRequest, signal?: AbortSignal) => Promise<FetchResult>;
64
- search?: (request: SearchRequest, signal?: AbortSignal) => Promise<SearchResult>;
65
- /** See `SearchSource`. */
66
- searchSources?: readonly SearchSource[];
67
- /** See `FetchSource`. */
68
- fetchSources?: readonly FetchSource[];
69
- evidence: EvidenceSink;
70
- scope(conversation: string | number): {
71
- label: string;
72
- proxies: boolean;
73
- } | Promise<{
74
- label: string;
75
- proxies: boolean;
76
- }>;
77
- prices?: Partial<PriceTable>;
78
- redact?: {
79
- values: () => readonly string[];
80
- };
81
- backups?: readonly WebBackup[];
82
- classifyPage?: Decisions["classifyPage"];
83
- render?: {
84
- enabled: boolean;
85
- read(url: string, signal?: AbortSignal): Promise<RenderedPage>;
86
- };
87
- /** Text of a PDF the provider would not convert to markdown; null or blank is a PDF with no readable text. */
88
- pdf?: {
89
- text(bytes: Uint8Array, url: string, signal: AbortSignal): Promise<string | null>;
90
- maxBytes?: number;
91
- timeoutMs?: number;
92
- };
93
- /** How long the screening of a search answer's snippets may take in all; default `SNIPPET_SCREEN_TIMEOUT_MS`. */
94
- snippetScreenMs?: number;
95
- };
96
5
  export type WebFailure = BrowserFailure & {
97
6
  wall?: WallClass;
98
7
  };
99
- export type WebOutcome = {
100
- text: string;
101
- isError: boolean;
102
- details: Record<string, unknown>;
103
- usd: number;
104
- };
105
8
  export declare const WALLS: Record<WallClass, {
106
9
  code: "blocked" | "not_content";
107
10
  what: string;
@@ -112,15 +15,3 @@ export declare function wallFailure(subject: string, wall: WallClass, detail?: s
112
15
  /** The line before a page the model reads: an injection over the threshold first, whatever the wall; then a page not screened, an unjudged
113
16
  * wall or a score that is not a finite number. */
114
17
  export declare function pageNotice(verdict: PageVerdict | null | undefined): string;
115
- export declare function filedBody(result: string): string;
116
- export type WebTools = {
117
- fetch(conversation: string | number, args: {
118
- url?: unknown;
119
- format?: unknown;
120
- }, signal?: AbortSignal): Promise<WebOutcome>;
121
- search(conversation: string | number, args: {
122
- query?: unknown;
123
- n?: unknown;
124
- }, signal?: AbortSignal): Promise<WebOutcome>;
125
- };
126
- export declare function createWebTools(options: WebToolsOptions): WebTools;