@parcha/pi-browser 0.0.0-bootstrap.0 → 0.1.0-beta.13

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 (104) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/LICENSE +202 -0
  3. package/NOTICE +33 -0
  4. package/README.md +328 -1
  5. package/dist/coding-agent-local.d.ts +16 -0
  6. package/dist/coding-agent-local.js +138 -0
  7. package/dist/coding-agent.d.ts +78 -0
  8. package/dist/coding-agent.js +446 -0
  9. package/dist/core/contract.d.ts +26 -0
  10. package/dist/core/contract.js +154 -0
  11. package/dist/core/custody.d.ts +111 -0
  12. package/dist/core/custody.js +122 -0
  13. package/dist/core/decisions.d.ts +43 -0
  14. package/dist/core/decisions.js +4 -0
  15. package/dist/core/downloads.d.ts +35 -0
  16. package/dist/core/downloads.js +131 -0
  17. package/dist/core/effects.d.ts +63 -0
  18. package/dist/core/effects.js +256 -0
  19. package/dist/core/evidence.d.ts +43 -0
  20. package/dist/core/evidence.js +6 -0
  21. package/dist/core/failures.d.ts +28 -0
  22. package/dist/core/failures.js +59 -0
  23. package/dist/core/find.d.ts +32 -0
  24. package/dist/core/find.js +179 -0
  25. package/dist/core/guard.d.ts +6 -0
  26. package/dist/core/guard.js +24 -0
  27. package/dist/core/host.d.ts +279 -0
  28. package/dist/core/host.js +2 -0
  29. package/dist/core/images.d.ts +37 -0
  30. package/dist/core/images.js +60 -0
  31. package/dist/core/lease.d.ts +16 -0
  32. package/dist/core/lease.js +30 -0
  33. package/dist/core/receipts.d.ts +19 -0
  34. package/dist/core/receipts.js +22 -0
  35. package/dist/core/redact.d.ts +13 -0
  36. package/dist/core/redact.js +83 -0
  37. package/dist/core/session-control.d.ts +25 -0
  38. package/dist/core/session-control.js +75 -0
  39. package/dist/core/sites.d.ts +33 -0
  40. package/dist/core/sites.js +102 -0
  41. package/dist/core/tools.d.ts +37 -0
  42. package/dist/core/tools.js +170 -0
  43. package/dist/core/uri.d.ts +11 -0
  44. package/dist/core/uri.js +37 -0
  45. package/dist/core/usage.d.ts +38 -0
  46. package/dist/core/usage.js +44 -0
  47. package/dist/core/web.d.ts +98 -0
  48. package/dist/core/web.js +327 -0
  49. package/dist/driver/stagehand.d.ts +25 -0
  50. package/dist/driver/stagehand.js +141 -0
  51. package/dist/durable-result.d.ts +6 -0
  52. package/dist/durable-result.js +2 -0
  53. package/dist/durable.d.ts +75 -0
  54. package/dist/durable.js +484 -0
  55. package/dist/index.d.ts +18 -0
  56. package/dist/index.js +19 -0
  57. package/dist/providers/browserbase-net.d.ts +13 -0
  58. package/dist/providers/browserbase-net.js +96 -0
  59. package/dist/providers/browserbase.d.ts +152 -0
  60. package/dist/providers/browserbase.js +262 -0
  61. package/dist/providers/cdp-call.d.ts +6 -0
  62. package/dist/providers/cdp-call.js +25 -0
  63. package/dist/providers/cdp.d.ts +48 -0
  64. package/dist/providers/cdp.js +353 -0
  65. package/dist/providers/http.d.ts +2 -0
  66. package/dist/providers/http.js +21 -0
  67. package/dist/providers/kernel.d.ts +49 -0
  68. package/dist/providers/kernel.js +246 -0
  69. package/dist/providers/shared.d.ts +47 -0
  70. package/dist/providers/shared.js +82 -0
  71. package/dist/recorder/credential.d.ts +9 -0
  72. package/dist/recorder/credential.js +49 -0
  73. package/dist/recorder/follow.d.ts +26 -0
  74. package/dist/recorder/follow.js +138 -0
  75. package/dist/recorder/frames.d.ts +80 -0
  76. package/dist/recorder/frames.js +309 -0
  77. package/dist/recorder/index.d.ts +3 -0
  78. package/dist/recorder/index.js +6 -0
  79. package/dist/recorder/jpeg.d.ts +5 -0
  80. package/dist/recorder/jpeg.js +34 -0
  81. package/dist/store.d.ts +56 -0
  82. package/dist/store.js +196 -0
  83. package/dist/testing/backend.d.ts +231 -0
  84. package/dist/testing/backend.js +414 -0
  85. package/dist/testing/driver.d.ts +28 -0
  86. package/dist/testing/driver.js +32 -0
  87. package/dist/testing/index.d.ts +4 -0
  88. package/dist/testing/index.js +4 -0
  89. package/dist/testing/pages.d.ts +3 -0
  90. package/dist/testing/pages.js +10 -0
  91. package/dist/testing/sentinels.d.ts +29 -0
  92. package/dist/testing/sentinels.js +38 -0
  93. package/dist/vendor/stagehand-facade/contract.d.ts +348 -0
  94. package/dist/vendor/stagehand-facade/contract.js +155 -0
  95. package/dist/vendor/stagehand-facade/runtime.d.ts +90 -0
  96. package/dist/vendor/stagehand-facade/runtime.js +1640 -0
  97. package/dist/vendor/stagehand-facade/screenshot-transport.d.ts +15 -0
  98. package/dist/vendor/stagehand-facade/screenshot-transport.js +51 -0
  99. package/dist/vendor/stagehand-facade/tools.d.ts +31 -0
  100. package/dist/vendor/stagehand-facade/tools.js +139 -0
  101. package/dist/web.d.ts +41 -0
  102. package/dist/web.js +38 -0
  103. package/package.json +125 -1
  104. package/src/vendor/stagehand-facade/UPSTREAM.json +24 -0
@@ -0,0 +1,22 @@
1
+ import { createHash } from "node:crypto";
2
+ export const sha256Hex = (bytes) => createHash("sha256").update(bytes).digest("hex");
3
+ /** To a tenth; never negative; null for a bad date. A frame sits slightly before its offset. */
4
+ export function recordingOffsetS(createdAt, at) {
5
+ const start = Date.parse(createdAt);
6
+ const end = typeof at === "number" ? at : at.getTime();
7
+ return Number.isFinite(start) && Number.isFinite(end) ? Math.max(0, Math.round((end - start) / 100) / 10) : null;
8
+ }
9
+ /** A fact that does not apply is absent, never null, so a receipt header has no line for it. */
10
+ export function receiptFacts(read) {
11
+ const id = read.session?.resourceId ?? null;
12
+ const offset = id && read.recorded && read.session ? recordingOffsetS(read.session.createdAt, read.at ?? Date.now()) : null;
13
+ return { sha256: sha256Hex(read.body), ...(id ? { session: id } : {}), ...(offset !== null ? { recording_at_s: offset } : {}) };
14
+ }
15
+ const FACT_ORDER = ["requested_url", "final_url", "title", "status_code", "content_type", "sha256", "extractor", "via", "session", "recording_at_s", "page_guard"];
16
+ /** A key the order does not list follows the listed ones, so a fact added to the record never goes missing from a
17
+ * receipt. */
18
+ export function orderFacts(facts) {
19
+ const listed = new Set(FACT_ORDER);
20
+ const keys = [...FACT_ORDER, ...Object.keys(facts).filter((key) => !listed.has(key))];
21
+ return Object.fromEntries(keys.flatMap((key) => (facts[key] === undefined ? [] : [[key, facts[key]]])));
22
+ }
@@ -0,0 +1,13 @@
1
+ export type Redact = (text: string) => string;
2
+ /** Scrubbing a shorter string everywhere would destroy the text around it, and no credential is that short. */
3
+ export declare const MIN_REDACTED_VALUE_LENGTH = 8;
4
+ /** `values()` is read at every call; each value is scrubbed raw, URL-encoded fully, and in every spelling web_fetch can
5
+ * send it in (fetchedSpellings), longest first. */
6
+ export declare function createRedactor(values?: () => readonly string[]): Redact;
7
+ /** A credential can sit in any query value, the fragment or the userinfo, so every query value is replaced (names stay)
8
+ * and the fragment and userinfo are dropped before `redact` runs. A non-http(s) URL is only redacted. */
9
+ export declare function scrubPageUrl(raw: string, redact: Redact): string;
10
+ /** A fetch's final URL for the model: a query value or fragment stays only where the requested URL has it; userinfo never does. */
11
+ export declare function scrubFetchedUrl(raw: string, requested: string, redact: Redact): string;
12
+ /** Every string inside `value`, object keys included, passed through `redact`. */
13
+ export declare function redactDeep<T>(value: T, redact: Redact): T;
@@ -0,0 +1,83 @@
1
+ import { fetchedSpellings } from "./uri.js";
2
+ const REDACTED = "[redacted]";
3
+ /** Scrubbing a shorter string everywhere would destroy the text around it, and no credential is that short. */
4
+ export const MIN_REDACTED_VALUE_LENGTH = 8;
5
+ const SHAPES = [
6
+ [/([?&](?:signingKey|api_?key|(?:access_)?token|key|jwt|signature)=)[^&#\s"'<>]+/gi, `$1${REDACTED}`],
7
+ // OpenAI-style secret keys, Browserbase live and test keys, Google API keys.
8
+ [/\b(sk-[A-Za-z0-9_-]{6})[A-Za-z0-9_-]+/g, `$1${REDACTED}`],
9
+ [/\b(bb_(?:live|test)_[A-Za-z0-9]{4})[A-Za-z0-9_-]+/g, `$1${REDACTED}`],
10
+ [/\bAIza[0-9A-Za-z_-]{30,}/g, `AIza${REDACTED}`],
11
+ [/\b(Bearer\s+)[A-Za-z0-9._~+/=-]{8,}/gi, `$1${REDACTED}`],
12
+ ];
13
+ /** `values()` is read at every call; each value is scrubbed raw, URL-encoded fully, and in every spelling web_fetch can
14
+ * send it in (fetchedSpellings), longest first. */
15
+ export function createRedactor(values = () => []) {
16
+ return (text) => {
17
+ const forms = new Set([...values()].filter((value) => typeof value === "string" && value.length >= MIN_REDACTED_VALUE_LENGTH).flatMap((value) => [value, encodeURIComponent(value), ...fetchedSpellings(value)]));
18
+ let out = text;
19
+ for (const form of [...forms].sort((a, b) => b.length - a.length))
20
+ out = out.split(form).join(REDACTED);
21
+ for (const [shape, replacement] of SHAPES)
22
+ out = out.replace(shape, replacement);
23
+ return out;
24
+ };
25
+ }
26
+ /** A credential can sit in any query value, the fragment or the userinfo, so every query value is replaced (names stay)
27
+ * and the fragment and userinfo are dropped before `redact` runs. A non-http(s) URL is only redacted. */
28
+ export function scrubPageUrl(raw, redact) {
29
+ let url;
30
+ try {
31
+ url = new URL(raw);
32
+ }
33
+ catch {
34
+ return redact(raw);
35
+ }
36
+ if (url.protocol !== "http:" && url.protocol !== "https:")
37
+ return redact(raw);
38
+ const names = [...new Set(url.searchParams.keys())];
39
+ return redact(`${url.origin}${url.pathname}${names.length ? `?${names.map((n) => `${encodeURIComponent(n)}=${REDACTED}`).join("&")}` : ""}`);
40
+ }
41
+ /** A fetch's final URL for the model: a query value or fragment stays only where the requested URL has it; userinfo never does. */
42
+ export function scrubFetchedUrl(raw, requested, redact) {
43
+ let url, asked;
44
+ try {
45
+ url = new URL(raw);
46
+ }
47
+ catch {
48
+ return redact(raw);
49
+ }
50
+ if (url.protocol !== "http:" && url.protocol !== "https:")
51
+ return redact(raw);
52
+ try {
53
+ asked = new URL(requested);
54
+ }
55
+ catch {
56
+ return scrubPageUrl(raw, redact);
57
+ }
58
+ const decoded = (text) => { try {
59
+ return decodeURIComponent(text.replace(/\+/g, " "));
60
+ }
61
+ catch {
62
+ return text;
63
+ } };
64
+ const pairsOf = (search) => search.slice(1).split("&").filter(Boolean).map((pair) => {
65
+ const at = pair.indexOf("=");
66
+ return at < 0 ? { pair, key: pair, value: "" } : { pair, key: pair.slice(0, at), value: pair.slice(at + 1) };
67
+ });
68
+ const sent = new Set(pairsOf(asked.search).map(({ key, value }) => `${decoded(key)}\0${decoded(value)}`));
69
+ const query = pairsOf(url.search).map(({ pair, key, value }) => (sent.has(`${decoded(key)}\0${decoded(value)}`) ? pair : `${key}=${REDACTED}`));
70
+ const fragment = url.hash && url.hash === asked.hash ? url.hash : "";
71
+ return redact(`${url.protocol}//${url.host}${url.pathname}${query.length ? `?${query.join("&")}` : ""}${fragment}`);
72
+ }
73
+ /** Every string inside `value`, object keys included, passed through `redact`. */
74
+ export function redactDeep(value, redact) {
75
+ if (typeof value === "string")
76
+ return redact(value);
77
+ if (Array.isArray(value))
78
+ return value.map((item) => redactDeep(item, redact));
79
+ if (value && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype) {
80
+ return Object.fromEntries(Object.entries(value).map(([key, item]) => [redact(key), redactDeep(item, redact)]));
81
+ }
82
+ return value;
83
+ }
@@ -0,0 +1,25 @@
1
+ import type { BrowserPolicy } from "./host.js";
2
+ export declare const DEFAULT_BROWSER_POLICY: Readonly<BrowserPolicy>;
3
+ export declare const CREATE_DEADLINE_MS = 60000;
4
+ export type KeyedSerializer = {
5
+ run<T>(key: string, work: () => Promise<T>): Promise<T>;
6
+ keys(): string[];
7
+ };
8
+ export declare function keyedSerializer(): KeyedSerializer;
9
+ export type IdleTracker<K = string> = {
10
+ activity(key: K, delta: number, idleMs?: number): void;
11
+ /** True while `fired` is the key's current timer and nothing is in flight: only then may an idle release go ahead. */
12
+ isCurrent(key: K, fired: NodeJS.Timeout): boolean;
13
+ cancel(key: K): void;
14
+ /** Safe mid-call: a key with calls in flight goes when the last one ends, and no timer is armed after it. */
15
+ forget(key: K): void;
16
+ clear(): void;
17
+ keys(): K[];
18
+ };
19
+ export declare function idleTracker<K = string>(options: {
20
+ idleMs: number;
21
+ onIdle(key: K, fired: NodeJS.Timeout, idleMs: number): void;
22
+ }): IdleTracker<K>;
23
+ /** Every environment variable that holds a provider key: each redactor in either adapter scrubs their values. */
24
+ export declare const PROVIDER_KEY_ENV: readonly string[];
25
+ export declare const providerKeyValues: (env: NodeJS.ProcessEnv, host?: () => readonly string[]) => string[];
@@ -0,0 +1,75 @@
1
+ export const DEFAULT_BROWSER_POLICY = Object.freeze({
2
+ proxies: false, verified: false, captcha: false, geolocation: null, region: null, contextId: null, sessionTimeoutS: 1800, idleReleaseS: 180, batchTimeoutMs: 60_000,
3
+ });
4
+ export const CREATE_DEADLINE_MS = 60_000;
5
+ export function keyedSerializer() {
6
+ const tails = new Map();
7
+ return {
8
+ run(key, work) {
9
+ const turn = (tails.get(key) ?? Promise.resolve()).then(work, work);
10
+ const tail = turn.then(() => undefined, () => undefined);
11
+ tails.set(key, tail);
12
+ void tail.then(() => { if (tails.get(key) === tail)
13
+ tails.delete(key); });
14
+ return turn;
15
+ },
16
+ keys: () => [...tails.keys()],
17
+ };
18
+ }
19
+ export function idleTracker(options) {
20
+ const entries = new Map();
21
+ return {
22
+ activity(key, delta, idleMs) {
23
+ const entry = entries.get(key) ?? { inFlight: 0, idleMs: idleMs ?? options.idleMs };
24
+ if (entry.timer)
25
+ clearTimeout(entry.timer);
26
+ entry.timer = undefined;
27
+ entry.inFlight = Math.max(0, entry.inFlight + delta);
28
+ if (idleMs !== undefined)
29
+ entry.idleMs = idleMs;
30
+ if (entry.forgotten && entry.inFlight === 0) {
31
+ entries.delete(key);
32
+ return;
33
+ }
34
+ entries.set(key, entry);
35
+ if (entry.inFlight > 0 || !(entry.idleMs > 0))
36
+ return;
37
+ const timer = setTimeout(() => options.onIdle(key, timer, entry.idleMs), entry.idleMs);
38
+ entry.timer = timer;
39
+ timer.unref?.();
40
+ },
41
+ isCurrent(key, fired) {
42
+ const entry = entries.get(key);
43
+ return entry?.timer === fired && entry.inFlight === 0;
44
+ },
45
+ cancel(key) {
46
+ const entry = entries.get(key);
47
+ if (entry?.timer)
48
+ clearTimeout(entry.timer);
49
+ if (entry)
50
+ entry.timer = undefined;
51
+ },
52
+ forget(key) {
53
+ const entry = entries.get(key);
54
+ if (!entry)
55
+ return;
56
+ if (entry.timer)
57
+ clearTimeout(entry.timer);
58
+ entry.timer = undefined;
59
+ if (entry.inFlight === 0)
60
+ entries.delete(key);
61
+ else
62
+ entry.forgotten = true;
63
+ },
64
+ clear() {
65
+ for (const entry of entries.values())
66
+ if (entry.timer)
67
+ clearTimeout(entry.timer);
68
+ entries.clear();
69
+ },
70
+ keys: () => [...entries.keys()],
71
+ };
72
+ }
73
+ /** Every environment variable that holds a provider key: each redactor in either adapter scrubs their values. */
74
+ export const PROVIDER_KEY_ENV = Object.freeze(["BROWSERBASE_API_KEY", "BB_API_KEY", "KERNEL_API_KEY"]);
75
+ export const providerKeyValues = (env, host) => [...PROVIDER_KEY_ENV.map((name) => env[name] ?? "").filter(Boolean), ...(host?.() ?? [])];
@@ -0,0 +1,33 @@
1
+ import type { ToolContract } from "./contract.js";
2
+ import type { ToolOutput } from "./custody.js";
3
+ import type { ChildRunner, SiteInfo, SiteRunPort } from "./host.js";
4
+ export declare const MAX_SITE_INSTRUCTIONS = 16000;
5
+ /** The site enum and the description render from the listing, which is configuration: every request sends the same
6
+ * text and keeps the prompt cache. */
7
+ export declare function useWebsiteContract(sites: readonly SiteInfo[]): ToolContract;
8
+ /** Only the declared shape crosses back to the model: a port's extra fields, such as capabilities or URLs, are dropped
9
+ * here, and an answer with both shapes or neither is no answer. */
10
+ export declare function siteAnswer(raw: unknown): {
11
+ run: {
12
+ id: string;
13
+ state: string;
14
+ };
15
+ } | {
16
+ report: string;
17
+ } | null;
18
+ export declare function useWebsite(args: {
19
+ site?: unknown;
20
+ request_id?: unknown;
21
+ instructions?: unknown;
22
+ }, port: SiteRunPort, sites: readonly SiteInfo[], ctx: {
23
+ signal: AbortSignal;
24
+ runChild: ChildRunner;
25
+ }): Promise<ToolOutput>;
26
+ export type LocalSite = {
27
+ title: string;
28
+ description: string;
29
+ startUrl: string;
30
+ };
31
+ /** `use_website` for a plain pi user: each task runs a child agent through the adapter's `runChild` and answers its
32
+ * report. A request_id runs once; a failed run may be asked again. */
33
+ export declare function localSites(sites: Record<string, LocalSite>): SiteRunPort;
@@ -0,0 +1,102 @@
1
+ export const MAX_SITE_INSTRUCTIONS = 16_000;
2
+ const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
3
+ const RUN_ID = /^[A-Za-z0-9_.:-]{1,200}$/;
4
+ const RUN_STATE = /^[a-z_]{1,40}$/;
5
+ /** The site enum and the description render from the listing, which is configuration: every request sends the same
6
+ * text and keeps the prompt cache. */
7
+ export function useWebsiteContract(sites) {
8
+ return {
9
+ name: "use_website",
10
+ label: "Use a website",
11
+ description: [
12
+ "Hand a task to an agent that works on one of these websites in its own browser, and get back what it found or did:",
13
+ ...sites.map((site) => `- ${site.site}: ${site.title}. ${site.description}`),
14
+ "Give a new request_id (a UUID) for each new task. Calling again with the request_id of a finished task answers its result without running it again; a task that failed runs again, and may repeat what it already did on the site.",
15
+ ].join("\n"),
16
+ parameters: {
17
+ type: "object", additionalProperties: false, required: ["site", "request_id", "instructions"],
18
+ properties: {
19
+ site: { type: "string", enum: sites.map((site) => site.site), description: "The website to use." },
20
+ request_id: { type: "string", description: "A UUID you choose for this task." },
21
+ instructions: { type: "string", maxLength: MAX_SITE_INSTRUCTIONS, description: "What to do on the website and what to report back." },
22
+ },
23
+ },
24
+ effect: "effect", replay: "safe", executionMode: "sequential", evidence: "none", listedWhen: "sites",
25
+ };
26
+ }
27
+ /** Only the declared shape crosses back to the model: a port's extra fields, such as capabilities or URLs, are dropped
28
+ * here, and an answer with both shapes or neither is no answer. */
29
+ export function siteAnswer(raw) {
30
+ if (!raw || typeof raw !== "object")
31
+ return null;
32
+ const { run, report } = raw;
33
+ if ((run === undefined) === (report === undefined))
34
+ return null;
35
+ if (report !== undefined)
36
+ return typeof report === "string" ? { report } : null;
37
+ const { id, state } = (run ?? {});
38
+ return typeof id === "string" && RUN_ID.test(id) && typeof state === "string" && RUN_STATE.test(state) ? { run: { id, state } } : null;
39
+ }
40
+ const siteOutput = (body, isError = false) => ({ content: [{ type: "text", text: JSON.stringify(body) }], ...(isError ? { isError: true } : {}) });
41
+ const siteRefusal = (message) => siteOutput({ ok: false, code: "refused", retryable: false, effect: "none", message }, true);
42
+ export async function useWebsite(args, port, sites, ctx) {
43
+ const site = sites.find((known) => known.site === args.site);
44
+ if (!site)
45
+ return siteRefusal(`site is one of: ${sites.map((known) => known.site).join(", ")}`);
46
+ if (typeof args.request_id !== "string" || !UUID.test(args.request_id))
47
+ return siteRefusal("request_id is a UUID you choose for this task");
48
+ const instructions = typeof args.instructions === "string" ? args.instructions.trim() : "";
49
+ if (!instructions || instructions.length > MAX_SITE_INSTRUCTIONS)
50
+ return siteRefusal(`instructions say what to do on the site, in at most ${MAX_SITE_INSTRUCTIONS} characters`);
51
+ const head = { ok: true, site: site.site, request_id: args.request_id };
52
+ let raw;
53
+ try {
54
+ raw = await port.use({ site: site.site, requestId: args.request_id, instructions }, ctx);
55
+ }
56
+ catch {
57
+ // A port's error text can carry its grant or a URL: none of it is forwarded.
58
+ if (ctx.signal.aborted)
59
+ return siteOutput({ ok: false, code: "aborted", retryable: true, effect: "possibly_effected", message: "The call was cancelled, and the site's task may already have changed the site. Calling again with the same request_id runs an unfinished task again, and it may repeat what it did." }, true);
60
+ return siteOutput({ ok: false, code: "command_failed", retryable: true, effect: "possibly_effected", message: `The ${site.site} task failed, and may already have changed the site. Calling use_website again with the same request_id runs it again, and it may repeat what it did.` }, true);
61
+ }
62
+ const parsed = siteAnswer(raw);
63
+ if (!parsed)
64
+ return siteOutput({ ok: false, code: "command_failed", retryable: false, effect: "possibly_effected", message: `The ${site.site} runner answered neither a started task nor a report.` }, true);
65
+ if ("report" in parsed)
66
+ return siteOutput({ ...head, report: parsed.report });
67
+ return siteOutput({ ...head, run: parsed.run, next: "The site's task was started; its result arrives through your host. Do not call use_website again for this request." });
68
+ }
69
+ const childPrompt = (site, entry, instructions) => [
70
+ `You are doing one task on ${entry.title} (${site}) for another agent, in your own browser.`,
71
+ `Start at ${entry.startUrl}.`,
72
+ `Task: ${instructions}`,
73
+ "Use the browser tools. Do not ask questions. Finish with a short report of what you found or did.",
74
+ ].join("\n");
75
+ /** `use_website` for a plain pi user: each task runs a child agent through the adapter's `runChild` and answers its
76
+ * report. A request_id runs once; a failed run may be asked again. */
77
+ export function localSites(sites) {
78
+ for (const [site, entry] of Object.entries(sites)) {
79
+ if (!/^https?:\/\//.test(entry.startUrl))
80
+ throw new Error(`site ${site}: startUrl must be an http or https URL`);
81
+ }
82
+ const runs = new Map();
83
+ return {
84
+ async list() {
85
+ return Object.entries(sites).map(([site, entry]) => ({ site, title: entry.title, description: entry.description }));
86
+ },
87
+ async use({ site, requestId, instructions }, { signal, runChild }) {
88
+ const entry = Object.hasOwn(sites, site) ? sites[site] : undefined;
89
+ if (!entry)
90
+ throw new Error(`no site named ${site}`);
91
+ const key = `${site}\u0000${requestId}`;
92
+ let run = runs.get(key);
93
+ if (!run) {
94
+ run = runChild({ site, requestId, prompt: childPrompt(site, entry, instructions) }, signal);
95
+ runs.set(key, run);
96
+ run.catch(() => { if (runs.get(key) === run)
97
+ runs.delete(key); });
98
+ }
99
+ return { report: await run };
100
+ },
101
+ };
102
+ }
@@ -0,0 +1,37 @@
1
+ import { type BrowserDriver, type CustodyPort, type ToolOutput } from "./custody.js";
2
+ import { type EvidenceSink } from "./evidence.js";
3
+ import type { Decisions } from "./decisions.js";
4
+ import { type ScreenshotOptions } from "./images.js";
5
+ import { type Redact } from "./redact.js";
6
+ export type PageDriver = BrowserDriver & {
7
+ snapshot(options?: {
8
+ includeIframes?: boolean;
9
+ }): Promise<string>;
10
+ run(input: {
11
+ code?: string;
12
+ actions?: unknown[];
13
+ }): Promise<unknown>;
14
+ /** The page's URL, cheaply: no page content is read. */
15
+ url(): Promise<string>;
16
+ screenshot(options: ScreenshotOptions): Promise<{
17
+ data: string;
18
+ mimeType: string;
19
+ }>;
20
+ page(): Promise<{
21
+ url: string;
22
+ title: string;
23
+ text: string;
24
+ html: string;
25
+ }>;
26
+ };
27
+ export type ToolCall = {
28
+ callId: string;
29
+ conversationId: number;
30
+ signal: AbortSignal | undefined;
31
+ label: string;
32
+ redact: Redact;
33
+ evidence: EvidenceSink;
34
+ classifyPage?: Decisions["classifyPage"];
35
+ };
36
+ export type ToolImpl<D extends BrowserDriver = BrowserDriver> = (args: any, port: CustodyPort<D>, call: ToolCall) => Promise<ToolOutput>;
37
+ export declare function pageTools(): Record<"snapshot" | "run" | "screenshot" | "browser_read", ToolImpl<PageDriver>>;
@@ -0,0 +1,170 @@
1
+ import { BrowserFailureError } from "./custody.js";
2
+ import { defaultInline } from "./evidence.js";
3
+ import { classifyBrowserError } from "./failures.js";
4
+ import { createRepeatGuard } from "./guard.js";
5
+ import { captureWithinBudget } from "./images.js";
6
+ import { orderFacts, receiptFacts, sha256Hex } from "./receipts.js";
7
+ import { scrubPageUrl } from "./redact.js";
8
+ import { pageNotice, wallFailure, wallOf } from "./web.js";
9
+ const WHATS = ["markdown", "text", "html", "url", "title"];
10
+ const text = (value, isError = false) => ({ content: [{ type: "text", text: typeof value === "string" ? value : JSON.stringify(value) }], ...(isError ? { isError: true } : {}) });
11
+ const withNews = (news, body) => (news ? `${news}\n\n${body}` : body);
12
+ const pageUrl = (call, raw) => scrubPageUrl(raw, call.redact);
13
+ /** A cut run that was observed and sent nothing that left the browser is safe to run again. */
14
+ const harmless = (p) => p.observed === true && !(p.sent ?? []).some((r) => r.held !== "denied");
15
+ function interruptedNotice(p, now) {
16
+ const head = `Your run call ${p.callId}${p.url ? ` on ${p.url}` : ""} was interrupted`;
17
+ if (harmless(p))
18
+ return `${head} before it sent any request that changes anything; it is safe to run again. The page is now ${now}.`;
19
+ const sent = (p.sent ?? []).filter((r) => r.held !== "denied").map((r) => `${r.method} ${r.origin}${r.path}`);
20
+ if (sent.length)
21
+ return `${head} after it sent ${sent.join(", ")}; the page is now ${now}. Check on the page whether that landed before acting again, and do not send it again if it did.`;
22
+ return `${head} and may have taken effect; the page is now ${now}. Check it with snapshot before acting again.`;
23
+ }
24
+ async function markdown(html, fallback) {
25
+ try {
26
+ const [{ parse }, { NodeHtmlMarkdown }] = await Promise.all([import("node-html-parser"), import("node-html-markdown")]);
27
+ const root = parse(html);
28
+ const main = root.querySelector("article") ?? root.querySelector("main") ?? root.querySelector("body") ?? root;
29
+ const md = NodeHtmlMarkdown.translate(main.toString(), { keepDataImages: false });
30
+ if (md.trim())
31
+ return { body: md, extractor: "readability-md", ext: "md" };
32
+ }
33
+ catch { }
34
+ return { body: fallback, extractor: "inner-text", ext: "txt" };
35
+ }
36
+ export function pageTools() {
37
+ const guards = new Map();
38
+ const guardOf = (conversationId) => guards.get(conversationId) ?? guards.set(conversationId, createRepeatGuard()).get(conversationId);
39
+ async function failureOf(error, effectful, port, call) {
40
+ if (error instanceof BrowserFailureError)
41
+ return error.failure;
42
+ const facts = { aborted: call.signal?.aborted === true };
43
+ const first = classifyBrowserError(error, effectful, facts);
44
+ if (first.code === "aborted" || first.code === "auth" || !(await port.ended().catch(() => false)))
45
+ return first;
46
+ return classifyBrowserError(error, effectful, { ...facts, sessionEnded: true });
47
+ }
48
+ async function perform(tool, args, port, call, effectful, body) {
49
+ const guard = guardOf(call.conversationId);
50
+ const refused = guard.check(tool, args);
51
+ if (refused)
52
+ return text(refused, true);
53
+ // Custody's news is told on this call whatever it ends in: a cut run is settled once it has been told.
54
+ let news = "";
55
+ try {
56
+ const s = await port.session();
57
+ news = s.notice ?? "";
58
+ if (s.interrupted) {
59
+ const now = pageUrl(call, await s.driver.url().catch(() => "gone"));
60
+ news = [news, interruptedNotice(s.interrupted, now)].filter(Boolean).join(" ");
61
+ await port.settle();
62
+ }
63
+ const out = await body(s, news);
64
+ guard.note(tool, args, null);
65
+ return out;
66
+ }
67
+ catch (error) {
68
+ let failure = await failureOf(error, effectful, port, call);
69
+ // A dropped CDP connection to a session the provider still runs: reconnect. A read runs once more; a run, which
70
+ // may have acted, is not repeated.
71
+ if (failure.code === "browser_unavailable" && !(error instanceof BrowserFailureError)) {
72
+ await port.dropped().catch(() => undefined);
73
+ if (effectful)
74
+ failure = { ...failure, retryable: true, message: "The connection to your browser session dropped; the session is still open, and your next browser call reconnects to it with its pages and cookies. This run may have acted before the drop: take a snapshot to see the page before running again." };
75
+ else {
76
+ let again = null;
77
+ try {
78
+ again = await port.session();
79
+ }
80
+ catch (reconnect) {
81
+ const refused = await failureOf(reconnect, effectful, port, call);
82
+ failure = refused.code === "aborted" || refused.code === "auth" ? refused : { ...refused, code: "browser_unavailable", retryable: false, message: "The connection to your browser session dropped and could not be re-established, though the session is still open. Call browser_relaunch for a fresh session (its pages and cookies are gone), or use web_fetch." };
83
+ }
84
+ if (again)
85
+ try {
86
+ const out = await body(again, news);
87
+ guard.note(tool, args, null);
88
+ return out;
89
+ }
90
+ catch (retried) {
91
+ failure = await failureOf(retried, effectful, port, call);
92
+ }
93
+ }
94
+ }
95
+ guard.note(tool, args, failure);
96
+ return text(news ? { ...failure, notice: news } : failure, true);
97
+ }
98
+ }
99
+ async function file(s, call, record) {
100
+ const facts = orderFacts({ ...record.facts, ...receiptFacts({ body: record.body, session: s.record, recorded: s.recorded }) });
101
+ const filed = await call.evidence.file(call.label, { ...record, facts });
102
+ return { path: filed?.path ?? null, bodyLine: filed?.bodyLine ?? null, sha256: facts.sha256 };
103
+ }
104
+ return {
105
+ snapshot: (args, port, call) => perform("snapshot", args ?? {}, port, call, false, async (s, news) => text(withNews(news, await s.driver.snapshot(args ?? {})))),
106
+ run: async (args, port, call) => {
107
+ if ((args?.code === undefined) === (args?.actions === undefined)) {
108
+ return text({ ok: false, code: "refused", retryable: false, effect: "none", message: "run requires exactly one of code or actions" }, true);
109
+ }
110
+ const codeSha = sha256Hex(JSON.stringify(args.code ?? args.actions));
111
+ return perform("run", args, port, call, true, async (s, news) => {
112
+ if (s.interrupted?.codeSha === codeSha && !harmless(s.interrupted)) {
113
+ return text({ ok: false, code: "effect_unknown", retryable: true, effect: "possibly_effected", message: `${news} This is the same code, so it is not run again now: check whether it landed, then call run again only if it did not.` }, true);
114
+ }
115
+ await port.dispatching({ callId: call.callId, codeSha, url: s.record.lastUrl, observed: s.effects?.holding === true });
116
+ const sent = [];
117
+ const stop = s.effects?.record((row) => { sent.push({ method: row.method, url: call.redact(`${row.origin}${row.path}`), held: row.held }); return port.journal(row); });
118
+ let value;
119
+ try {
120
+ value = await s.driver.run(args.code !== undefined ? { code: args.code } : { actions: args.actions });
121
+ }
122
+ finally {
123
+ await s.effects?.flush(call.signal).catch(() => undefined);
124
+ stop?.();
125
+ await port.settle();
126
+ }
127
+ const url = await s.driver.url().catch(() => null);
128
+ // Compared as custody keeps it, so a page with a query value never looks new on every run.
129
+ if (url && scrubPageUrl(url, call.redact) !== s.record.lastUrl)
130
+ await port.navigated(url);
131
+ const reported = args.actions !== undefined && value && typeof value === "object" && typeof value.url === "string" ? { ...value, url: pageUrl(call, value.url) } : value;
132
+ const shown = typeof reported === "string" ? reported : reported === undefined ? "(run completed; no return value)" : JSON.stringify(reported, null, 2) ?? String(reported);
133
+ return { ...text(withNews(news, shown)), ...(sent.length ? { details: { sent } } : {}) };
134
+ });
135
+ },
136
+ screenshot: (args, port, call) => {
137
+ const { ask: _ask, ...requested } = args ?? {};
138
+ return perform("screenshot", args ?? {}, port, call, false, async (s, news) => {
139
+ const shot = await captureWithinBudget((options) => s.driver.screenshot(options), requested);
140
+ const url = pageUrl(call, await s.driver.url());
141
+ const receipt = await file(s, call, { tool: "screenshot", args: requested, status: "ok", facts: { final_url: url }, body: Buffer.from(shot.data, "base64"), ext: shot.size.type === "png" ? "png" : "jpg" });
142
+ const first = shot.adjusted?.first;
143
+ 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 the viewport at ${shot.size.width}x${shot.size.height}`;
144
+ const lines = [news, `url: ${url}`, `evidence: ${receipt.path ?? "(not filed)"}`, adjusted].filter(Boolean).join("\n");
145
+ return { content: [{ type: "text", text: lines }, { type: "image", data: shot.data, mimeType: shot.mimeType }], details: { evidence: receipt.path, sha256: receipt.sha256 } };
146
+ });
147
+ },
148
+ browser_read: (args, port, call) => {
149
+ const what = WHATS.includes(args?.what) ? args.what : "markdown";
150
+ return perform("browser_read", { what }, port, call, false, async (s, news) => {
151
+ const page = await s.driver.page();
152
+ const read = what === "markdown" ? await markdown(page.html, page.text)
153
+ : what === "html" ? { body: page.html, extractor: "raw", ext: "html" }
154
+ : what === "text" ? { body: page.text, extractor: "inner-text", ext: "txt" }
155
+ : { body: what === "url" ? pageUrl(call, page.url) : page.title, ext: "txt" };
156
+ const body = call.redact(read.body);
157
+ const [url, title] = [pageUrl(call, page.url), call.redact(page.title)];
158
+ const verdict = call.classifyPage ? await call.classifyPage({ url, status: null, contentType: "text/html", text: page.text }).catch(() => ({ wall: "unjudged", injection: null, confidence: null })) : null;
159
+ const wall = wallOf(verdict);
160
+ const facts = { final_url: url, title, ...(read.extractor ? { extractor: read.extractor } : {}), via: "browser", ...(verdict?.guard ? { page_guard: call.redact(verdict.guard) } : {}) };
161
+ const receipt = await file(s, call, { tool: "browser_read", args: { what }, status: wall ? "failed" : "ok", facts, body, ext: read.ext });
162
+ if (wall)
163
+ throw new BrowserFailureError({ ...wallFailure(`The browser is on ${url}`, wall, call.redact(page.text)), evidence: receipt.path });
164
+ const prefix = `${news ? `${news}\n\n` : ""}url: ${url}\ntitle: ${title}\n${pageNotice(verdict)}evidence: ${receipt.path ?? "(not filed)"}\n---\n`;
165
+ const shown = call.evidence.inline ? call.evidence.inline(body, { path: receipt.path, bodyLine: receipt.bodyLine, prefix, filed: body }) : defaultInline(body, { path: receipt.path, prefix });
166
+ return { content: [{ type: "text", text: shown }], details: { evidence: receipt.path, sha256: receipt.sha256, url } };
167
+ });
168
+ },
169
+ };
170
+ }
@@ -0,0 +1,11 @@
1
+ /** Percent-encodes, as UTF-8, what RFC 3986 refuses after a URL's authority. */
2
+ export declare const encodeRefused: (part: string) => string;
3
+ /** What a URL keeps after its authority, as fetchableUrl sends it: the first '#' stays the fragment's, the rest is
4
+ * encodeRefused. */
5
+ export declare function encodeAfterAuthority(rest: string): string;
6
+ /** Every spelling fetchableUrl can give `value` inside a URL, from the same encoders: holding the URL's first '#' or after
7
+ * it, and with a trailing incomplete escape either encoded or completed by hex digits that follow it in the URL (the
8
+ * encoder looks two characters ahead of a '%', so a two-digit probe after the value decides it, then is cut off). */
9
+ export declare function fetchedSpellings(value: string): string[];
10
+ /** Fetch APIs refuse what RFC 3986 does not allow (Browserbase: 400 `url must match format "uri"`) though a browser takes it raw. */
11
+ export declare function fetchableUrl(raw: string): string;
@@ -0,0 +1,37 @@
1
+ const NOT_IN_RFC3986 = /%(?![0-9A-Fa-f]{2})|[^A-Za-z0-9\-._~!$&'()*+,;=:@/?%]/gu;
2
+ /** Percent-encodes, as UTF-8, what RFC 3986 refuses after a URL's authority. */
3
+ export const encodeRefused = (part) => part.replace(NOT_IN_RFC3986, (c) => { try {
4
+ return encodeURIComponent(c);
5
+ }
6
+ catch {
7
+ return c;
8
+ } });
9
+ /** What a URL keeps after its authority, as fetchableUrl sends it: the first '#' stays the fragment's, the rest is
10
+ * encodeRefused. */
11
+ export function encodeAfterAuthority(rest) {
12
+ const hash = rest.indexOf("#");
13
+ return hash < 0 ? encodeRefused(rest) : `${encodeRefused(rest.slice(0, hash))}#${encodeRefused(rest.slice(hash + 1))}`;
14
+ }
15
+ /** Every spelling fetchableUrl can give `value` inside a URL, from the same encoders: holding the URL's first '#' or after
16
+ * it, and with a trailing incomplete escape either encoded or completed by hex digits that follow it in the URL (the
17
+ * encoder looks two characters ahead of a '%', so a two-digit probe after the value decides it, then is cut off). */
18
+ export function fetchedSpellings(value) {
19
+ const probe = "AA";
20
+ return [encodeRefused, encodeAfterAuthority].flatMap((encode) => [encode(value), encode(value + probe).slice(0, -probe.length)]);
21
+ }
22
+ /** Fetch APIs refuse what RFC 3986 does not allow (Browserbase: 400 `url must match format "uri"`) though a browser takes it raw. */
23
+ export function fetchableUrl(raw) {
24
+ const hostStart = raw.indexOf("//") + 2;
25
+ const hostLength = raw.slice(hostStart).search(/[/?#]/);
26
+ const authority = hostLength < 0 ? raw : raw.slice(0, hostStart + hostLength);
27
+ const rest = hostLength < 0 ? "" : raw.slice(hostStart + hostLength);
28
+ const encoded = encodeAfterAuthority(rest);
29
+ if (/^[\x21-\x7e]*$/.test(authority))
30
+ return authority + encoded;
31
+ try {
32
+ return new URL(authority).href.replace(/\/$/, "") + encoded;
33
+ }
34
+ catch {
35
+ return authority + encoded;
36
+ }
37
+ }