@parcha/pi-browser 0.0.0-stage → 0.1.0-beta.14
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/CHANGELOG.md +23 -0
- package/LICENSE +202 -0
- package/NOTICE +33 -0
- package/README.md +348 -2
- package/dist/coding-agent-local.d.ts +16 -0
- package/dist/coding-agent-local.js +138 -0
- package/dist/coding-agent.d.ts +79 -0
- package/dist/coding-agent.js +448 -0
- package/dist/core/contract.d.ts +26 -0
- package/dist/core/contract.js +154 -0
- package/dist/core/custody.d.ts +117 -0
- package/dist/core/custody.js +126 -0
- package/dist/core/decisions.d.ts +43 -0
- package/dist/core/decisions.js +4 -0
- package/dist/core/downloads.d.ts +35 -0
- package/dist/core/downloads.js +131 -0
- package/dist/core/effects.d.ts +63 -0
- package/dist/core/effects.js +256 -0
- package/dist/core/evidence.d.ts +43 -0
- package/dist/core/evidence.js +6 -0
- package/dist/core/failures.d.ts +36 -0
- package/dist/core/failures.js +68 -0
- package/dist/core/find.d.ts +32 -0
- package/dist/core/find.js +179 -0
- package/dist/core/guard.d.ts +6 -0
- package/dist/core/guard.js +25 -0
- package/dist/core/host.d.ts +328 -0
- package/dist/core/host.js +2 -0
- package/dist/core/images.d.ts +37 -0
- package/dist/core/images.js +60 -0
- package/dist/core/lease.d.ts +16 -0
- package/dist/core/lease.js +30 -0
- package/dist/core/receipts.d.ts +19 -0
- package/dist/core/receipts.js +22 -0
- package/dist/core/redact.d.ts +13 -0
- package/dist/core/redact.js +83 -0
- package/dist/core/session-control.d.ts +25 -0
- package/dist/core/session-control.js +75 -0
- package/dist/core/sites.d.ts +33 -0
- package/dist/core/sites.js +102 -0
- package/dist/core/tools.d.ts +72 -0
- package/dist/core/tools.js +200 -0
- package/dist/core/uri.d.ts +11 -0
- package/dist/core/uri.js +37 -0
- package/dist/core/usage.d.ts +19 -0
- package/dist/core/usage.js +44 -0
- package/dist/core/web.d.ts +98 -0
- package/dist/core/web.js +327 -0
- package/dist/driver/extension-worker.d.ts +6 -0
- package/dist/driver/extension-worker.js +121 -0
- package/dist/driver/stagehand.d.ts +25 -0
- package/dist/driver/stagehand.js +91 -0
- package/dist/durable-result.d.ts +6 -0
- package/dist/durable-result.js +2 -0
- package/dist/durable.d.ts +79 -0
- package/dist/durable.js +582 -0
- package/dist/index.d.ts +19 -0
- package/dist/index.js +20 -0
- package/dist/providers/browserbase-net.d.ts +13 -0
- package/dist/providers/browserbase-net.js +96 -0
- package/dist/providers/browserbase.d.ts +152 -0
- package/dist/providers/browserbase.js +262 -0
- package/dist/providers/cdp-call.d.ts +6 -0
- package/dist/providers/cdp-call.js +25 -0
- package/dist/providers/cdp.d.ts +55 -0
- package/dist/providers/cdp.js +423 -0
- package/dist/providers/http.d.ts +2 -0
- package/dist/providers/http.js +21 -0
- package/dist/providers/kernel.d.ts +49 -0
- package/dist/providers/kernel.js +246 -0
- package/dist/providers/shared.d.ts +47 -0
- package/dist/providers/shared.js +82 -0
- package/dist/recorder/credential.d.ts +9 -0
- package/dist/recorder/credential.js +49 -0
- package/dist/recorder/follow.d.ts +26 -0
- package/dist/recorder/follow.js +138 -0
- package/dist/recorder/frames.d.ts +80 -0
- package/dist/recorder/frames.js +309 -0
- package/dist/recorder/index.d.ts +4 -0
- package/dist/recorder/index.js +7 -0
- package/dist/recorder/jpeg.d.ts +8 -0
- package/dist/recorder/jpeg.js +70 -0
- package/dist/recorder/track.d.ts +107 -0
- package/dist/recorder/track.js +259 -0
- package/dist/store.d.ts +56 -0
- package/dist/store.js +196 -0
- package/dist/testing/backend.d.ts +231 -0
- package/dist/testing/backend.js +414 -0
- package/dist/testing/driver.d.ts +28 -0
- package/dist/testing/driver.js +32 -0
- package/dist/testing/index.d.ts +4 -0
- package/dist/testing/index.js +4 -0
- package/dist/testing/pages.d.ts +3 -0
- package/dist/testing/pages.js +10 -0
- package/dist/testing/sentinels.d.ts +29 -0
- package/dist/testing/sentinels.js +38 -0
- package/dist/vendor/stagehand-facade/contract.d.ts +348 -0
- package/dist/vendor/stagehand-facade/contract.js +155 -0
- package/dist/vendor/stagehand-facade/runtime.d.ts +90 -0
- package/dist/vendor/stagehand-facade/runtime.js +1640 -0
- package/dist/vendor/stagehand-facade/screenshot-transport.d.ts +15 -0
- package/dist/vendor/stagehand-facade/screenshot-transport.js +51 -0
- package/dist/vendor/stagehand-facade/tools.d.ts +31 -0
- package/dist/vendor/stagehand-facade/tools.js +139 -0
- package/dist/web.d.ts +41 -0
- package/dist/web.js +38 -0
- package/package.json +123 -4
- package/src/vendor/stagehand-facade/UPSTREAM.json +24 -0
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
import { BrowserFailureError } from "./custody.js";
|
|
2
|
+
import { defaultInline } from "./evidence.js";
|
|
3
|
+
import { browserFailure, 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 DROPPED_RUN = "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.";
|
|
11
|
+
const DROPPED_FOR_GOOD = "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.";
|
|
12
|
+
const text = (value, isError = false) => ({ content: [{ type: "text", text: typeof value === "string" ? value : JSON.stringify(value) }], ...(isError ? { isError: true } : {}) });
|
|
13
|
+
const withNews = (news, body) => (news ? `${news}\n\n${body}` : body);
|
|
14
|
+
const pageUrl = (call, raw) => scrubPageUrl(raw, call.redact);
|
|
15
|
+
/** A cut run that was observed and sent nothing that left the browser is safe to run again. */
|
|
16
|
+
const harmless = (p) => p.observed === true && !(p.sent ?? []).some((r) => r.held !== "denied");
|
|
17
|
+
function interruptedNotice(p, now) {
|
|
18
|
+
const where = `Your run call ${p.callId}${p.url ? ` on ${p.url}` : ""}`;
|
|
19
|
+
const sent = (p.sent ?? []).filter((r) => r.held !== "denied").map((r) => `${r.method} ${r.origin}${r.path}`);
|
|
20
|
+
if (p.finished) {
|
|
21
|
+
const head = `${where} ran, but the process stopped before its answer reached you`;
|
|
22
|
+
if (harmless(p))
|
|
23
|
+
return `${head}; it sent no request that changes anything, so it is safe to run again. The page is now ${now}.`;
|
|
24
|
+
if (sent.length)
|
|
25
|
+
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.`;
|
|
26
|
+
return `${head}, so what it did has taken effect; the page is now ${now}. Look at it with snapshot before acting again.`;
|
|
27
|
+
}
|
|
28
|
+
const head = `${where} was interrupted`;
|
|
29
|
+
if (harmless(p))
|
|
30
|
+
return `${head} before it sent any request that changes anything; it is safe to run again. The page is now ${now}.`;
|
|
31
|
+
if (sent.length)
|
|
32
|
+
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.`;
|
|
33
|
+
return `${head} and may have taken effect; the page is now ${now}. Check it with snapshot before acting again.`;
|
|
34
|
+
}
|
|
35
|
+
const factsOf = (p, now) => ({
|
|
36
|
+
callId: p.callId, urlAtDispatch: p.url, urlNow: now, observed: p.observed === true,
|
|
37
|
+
sent: p.watched ? (p.sent ?? []).map((r) => ({ method: r.method, url: `${r.origin}${r.path}`, held: r.held })) : null,
|
|
38
|
+
});
|
|
39
|
+
async function markdown(html, fallback) {
|
|
40
|
+
try {
|
|
41
|
+
const [{ parse }, { NodeHtmlMarkdown }] = await Promise.all([import("node-html-parser"), import("node-html-markdown")]);
|
|
42
|
+
const root = parse(html);
|
|
43
|
+
const main = root.querySelector("article") ?? root.querySelector("main") ?? root.querySelector("body") ?? root;
|
|
44
|
+
const md = NodeHtmlMarkdown.translate(main.toString(), { keepDataImages: false });
|
|
45
|
+
if (md.trim())
|
|
46
|
+
return { body: md, extractor: "readability-md", ext: "md" };
|
|
47
|
+
}
|
|
48
|
+
catch { }
|
|
49
|
+
return { body: fallback, extractor: "inner-text", ext: "txt" };
|
|
50
|
+
}
|
|
51
|
+
/** `guards` holds each conversation's repeat guard; a host that owns the conversation's lifecycle passes it to evict one. */
|
|
52
|
+
export function pageTools({ guards = new Map() } = {}) {
|
|
53
|
+
const guardOf = (conversationId) => guards.get(conversationId) ?? guards.set(conversationId, createRepeatGuard()).get(conversationId);
|
|
54
|
+
async function failureOf(error, effectful, port, call) {
|
|
55
|
+
if (error instanceof BrowserFailureError)
|
|
56
|
+
return error.failure;
|
|
57
|
+
const facts = { aborted: call.signal?.aborted === true };
|
|
58
|
+
const first = classifyBrowserError(error, effectful, facts);
|
|
59
|
+
if (first.code === "aborted" || first.code === "auth" || !(await port.ended().catch(() => false)))
|
|
60
|
+
return first;
|
|
61
|
+
return classifyBrowserError(error, effectful, { ...facts, sessionEnded: true });
|
|
62
|
+
}
|
|
63
|
+
/** A replay-unsafe action is journaled before it acts and marked finished after; the entry stays until a later call
|
|
64
|
+
* settles it, so a process that dies before pi commits the answer leaves a cut for the resumed run. */
|
|
65
|
+
async function dispatched(port, call, s, key, action) {
|
|
66
|
+
await port.dispatching({ callId: call.callId, codeSha: key, url: s.record.lastUrl, observed: s.effects?.holding === true, watched: s.effects != null });
|
|
67
|
+
try {
|
|
68
|
+
return await action();
|
|
69
|
+
}
|
|
70
|
+
finally {
|
|
71
|
+
await port.mark("finished", call.callId).catch(() => undefined);
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
async function perform(tool, args, port, call, kind, body) {
|
|
75
|
+
const effect = typeof kind === "object" ? kind.effect : null;
|
|
76
|
+
const effectful = effect !== null;
|
|
77
|
+
const guard = guardOf(call.conversationId);
|
|
78
|
+
const refused = guard.check(tool, args);
|
|
79
|
+
if (refused)
|
|
80
|
+
return text(refused, true);
|
|
81
|
+
// A cut is told once, on the call after it, whatever that call ends in. An identical action is refused until a look
|
|
82
|
+
// that follows the refusal settles the cut.
|
|
83
|
+
let news = "";
|
|
84
|
+
let cut = null;
|
|
85
|
+
let facts = null;
|
|
86
|
+
const tell = (out) => (facts ? { ...out, details: { ...out.details, pendingEffect: facts } } : out);
|
|
87
|
+
const done = (out) => { guard.note(tool, args, null); return tell(out); };
|
|
88
|
+
const fail = (failure) => { guard.note(tool, args, failure); return tell(text(news ? { ...failure, notice: news } : failure, true)); };
|
|
89
|
+
const looked = async (out) => { if (kind === "look" && cut?.refused)
|
|
90
|
+
await port.settle(cut.callId); return done(out); };
|
|
91
|
+
try {
|
|
92
|
+
const s = await port.session();
|
|
93
|
+
news = s.notice ?? "";
|
|
94
|
+
cut = s.interrupted;
|
|
95
|
+
const same = cut !== null && effect === cut.codeSha && !harmless(cut);
|
|
96
|
+
if (cut && (!cut.told || same))
|
|
97
|
+
facts = factsOf(cut, pageUrl(call, await s.driver.url().catch(() => "gone")));
|
|
98
|
+
if (cut && !cut.told) {
|
|
99
|
+
news = [news, interruptedNotice(cut, facts.urlNow)].filter(Boolean).join(" ");
|
|
100
|
+
await (harmless(cut) ? port.settle(cut.callId) : port.mark("told", cut.callId));
|
|
101
|
+
}
|
|
102
|
+
if (cut && same) {
|
|
103
|
+
await port.mark("refused", cut.callId);
|
|
104
|
+
return done(text(browserFailure("effect_unknown", `${news ? `${news} ` : ""}This is the same code, and it may already have taken effect, so it is not run again now: look at the page with snapshot or browser_read before you run this again.`, { retryable: true, effect: "possibly_effected" }), true));
|
|
105
|
+
}
|
|
106
|
+
return await looked(effect === null ? await body(s, news) : await dispatched(port, call, s, effect, () => body(s, news)));
|
|
107
|
+
}
|
|
108
|
+
catch (error) {
|
|
109
|
+
const failure = await failureOf(error, effectful, port, call);
|
|
110
|
+
if (failure.code !== "browser_unavailable" || error instanceof BrowserFailureError)
|
|
111
|
+
return fail(failure);
|
|
112
|
+
// A dropped CDP connection to a session the provider still runs: a read reconnects and runs once more; a run, which
|
|
113
|
+
// may have acted, is not repeated.
|
|
114
|
+
await port.dropped().catch(() => undefined);
|
|
115
|
+
if (effectful)
|
|
116
|
+
return fail({ ...failure, retryable: true, message: DROPPED_RUN });
|
|
117
|
+
let again;
|
|
118
|
+
try {
|
|
119
|
+
again = await port.session();
|
|
120
|
+
}
|
|
121
|
+
catch (reconnect) {
|
|
122
|
+
const refused = await failureOf(reconnect, effectful, port, call);
|
|
123
|
+
return fail(refused.code === "aborted" || refused.code === "auth" ? refused : { ...refused, code: "browser_unavailable", retryable: false, message: DROPPED_FOR_GOOD });
|
|
124
|
+
}
|
|
125
|
+
try {
|
|
126
|
+
return await looked(await body(again, news));
|
|
127
|
+
}
|
|
128
|
+
catch (retried) {
|
|
129
|
+
return fail(await failureOf(retried, effectful, port, call));
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
}
|
|
133
|
+
async function file(s, call, record) {
|
|
134
|
+
const facts = orderFacts({ ...record.facts, ...receiptFacts({ body: record.body, session: s.record, recorded: s.recorded }) });
|
|
135
|
+
const filed = await call.evidence.file(call.label, { ...record, facts });
|
|
136
|
+
return { path: filed?.path ?? null, bodyLine: filed?.bodyLine ?? null, sha256: facts.sha256 };
|
|
137
|
+
}
|
|
138
|
+
return {
|
|
139
|
+
snapshot: (args, port, call) => perform("snapshot", args ?? {}, port, call, "look", async (s, news) => text(withNews(news, await s.driver.snapshot(args ?? {})))),
|
|
140
|
+
run: async (args, port, call) => {
|
|
141
|
+
if ((args?.code === undefined) === (args?.actions === undefined)) {
|
|
142
|
+
return text(browserFailure("refused", "run requires exactly one of code or actions"), true);
|
|
143
|
+
}
|
|
144
|
+
const codeSha = sha256Hex(JSON.stringify(args.code ?? args.actions));
|
|
145
|
+
return perform("run", args, port, call, { effect: codeSha }, async (s, news) => {
|
|
146
|
+
const sent = [];
|
|
147
|
+
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); });
|
|
148
|
+
let value;
|
|
149
|
+
try {
|
|
150
|
+
value = await s.driver.run(args.code !== undefined ? { code: args.code } : { actions: args.actions });
|
|
151
|
+
}
|
|
152
|
+
finally {
|
|
153
|
+
await s.effects?.flush(call.signal).catch(() => undefined);
|
|
154
|
+
stop?.();
|
|
155
|
+
}
|
|
156
|
+
const url = await s.driver.url().catch(() => null);
|
|
157
|
+
// Compared as custody keeps it, so a page with a query value never looks new on every run.
|
|
158
|
+
if (url && scrubPageUrl(url, call.redact) !== s.record.lastUrl)
|
|
159
|
+
await port.navigated(url);
|
|
160
|
+
const reported = args.actions !== undefined && value && typeof value === "object" && typeof value.url === "string" ? { ...value, url: pageUrl(call, value.url) } : value;
|
|
161
|
+
const shown = typeof reported === "string" ? reported : reported === undefined ? "(run completed; no return value)" : JSON.stringify(reported, null, 2) ?? String(reported);
|
|
162
|
+
return { ...text(withNews(news, shown)), ...(sent.length ? { details: { sent } } : {}) };
|
|
163
|
+
});
|
|
164
|
+
},
|
|
165
|
+
screenshot: (args, port, call) => {
|
|
166
|
+
const { ask: asked, ...requested } = args ?? {};
|
|
167
|
+
const ask = typeof asked === "string" && asked.trim() ? asked.trim() : undefined;
|
|
168
|
+
return perform("screenshot", args ?? {}, port, call, "read", async (s, news) => {
|
|
169
|
+
const shot = await captureWithinBudget((options) => s.driver.screenshot(options), requested);
|
|
170
|
+
const url = pageUrl(call, await s.driver.url());
|
|
171
|
+
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" });
|
|
172
|
+
const first = shot.adjusted?.first;
|
|
173
|
+
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}`;
|
|
174
|
+
const lines = [news, `url: ${url}`, `evidence: ${receipt.path ?? "(not filed)"}`, adjusted].filter(Boolean).join("\n");
|
|
175
|
+
return { content: [{ type: "text", text: lines }, { type: "image", data: shot.data, mimeType: shot.mimeType }], details: { evidence: receipt.path, sha256: receipt.sha256, ...(ask ? { media: { ask } } : {}) } };
|
|
176
|
+
});
|
|
177
|
+
},
|
|
178
|
+
browser_read: (args, port, call) => {
|
|
179
|
+
const what = args?.what && WHATS.includes(args.what) ? args.what : "markdown";
|
|
180
|
+
return perform("browser_read", { what }, port, call, "look", async (s, news) => {
|
|
181
|
+
const page = await s.driver.page();
|
|
182
|
+
const read = what === "markdown" ? await markdown(page.html, page.text)
|
|
183
|
+
: what === "html" ? { body: page.html, extractor: "raw", ext: "html" }
|
|
184
|
+
: what === "text" ? { body: page.text, extractor: "inner-text", ext: "txt" }
|
|
185
|
+
: { body: what === "url" ? pageUrl(call, page.url) : page.title, ext: "txt" };
|
|
186
|
+
const body = call.redact(read.body);
|
|
187
|
+
const [url, title] = [pageUrl(call, page.url), call.redact(page.title)];
|
|
188
|
+
const verdict = call.classifyPage ? await call.classifyPage({ url, status: null, contentType: "text/html", text: page.text }).catch(() => ({ wall: "unjudged", injection: null, confidence: null })) : null;
|
|
189
|
+
const wall = wallOf(verdict);
|
|
190
|
+
const facts = { final_url: url, title, ...(read.extractor ? { extractor: read.extractor } : {}), via: "browser", ...(verdict?.guard ? { page_guard: call.redact(verdict.guard) } : {}) };
|
|
191
|
+
const receipt = await file(s, call, { tool: "browser_read", args: { what }, status: wall ? "failed" : "ok", facts, body, ext: read.ext });
|
|
192
|
+
if (wall)
|
|
193
|
+
throw new BrowserFailureError({ ...wallFailure(`The browser is on ${url}`, wall, call.redact(page.text)), evidence: receipt.path });
|
|
194
|
+
const prefix = `${news ? `${news}\n\n` : ""}url: ${url}\ntitle: ${title}\n${pageNotice(verdict)}evidence: ${receipt.path ?? "(not filed)"}\n---\n`;
|
|
195
|
+
const shown = call.evidence.inline ? call.evidence.inline(body, { path: receipt.path, bodyLine: receipt.bodyLine, prefix, filed: body }) : defaultInline(body, { path: receipt.path, prefix });
|
|
196
|
+
return { content: [{ type: "text", text: shown }], details: { evidence: receipt.path, sha256: receipt.sha256, url } };
|
|
197
|
+
});
|
|
198
|
+
},
|
|
199
|
+
};
|
|
200
|
+
}
|
|
@@ -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;
|
package/dist/core/uri.js
ADDED
|
@@ -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
|
+
}
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import { type PriceState, type PriceTable, type SessionRecord, type ToolUsage } from "./host.js";
|
|
2
|
+
/** Dollars per minute: unset or blank is unpriced; anything but a non-negative decimal is invalid. Zero is a price. */
|
|
3
|
+
export declare function sessionPrice(raw: string | null | undefined): {
|
|
4
|
+
prices: Pick<PriceTable, "sessionUsdPerHour">;
|
|
5
|
+
state: PriceState;
|
|
6
|
+
};
|
|
7
|
+
/** List prices with the host's overrides on top; an override of `null` is a deliberate gap. */
|
|
8
|
+
export declare const resolvePrices: (overrides?: Partial<PriceTable>) => PriceTable;
|
|
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
|
+
type Spent = SessionRecord["spent"];
|
|
13
|
+
export declare const startSpent: (createdAt: string) => Spent;
|
|
14
|
+
/** `final` (the release) tops up to the provider's minimum and marks the record, so a retried release adds nothing. */
|
|
15
|
+
export declare function sessionCharge(spent: Spent, at: string, prices: PriceTable, state?: PriceState, final?: boolean): {
|
|
16
|
+
spent: Spent;
|
|
17
|
+
usage: ToolUsage;
|
|
18
|
+
};
|
|
19
|
+
export {};
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
// A price the host does not know (`unpriced`) or cannot read (`invalid`) records seconds and charges nothing: a missing
|
|
2
|
+
// price never reads as free and never aborts a run.
|
|
3
|
+
import { LIST_PRICES } from "./host.js";
|
|
4
|
+
const DECIMAL = /^(\d+(\.\d*)?|\.\d+)(e[+-]?\d+)?$/i;
|
|
5
|
+
/** Dollars per minute: unset or blank is unpriced; anything but a non-negative decimal is invalid. Zero is a price. */
|
|
6
|
+
export function sessionPrice(raw) {
|
|
7
|
+
const text = String(raw ?? "").trim();
|
|
8
|
+
if (!text)
|
|
9
|
+
return { prices: { sessionUsdPerHour: null }, state: "unpriced" };
|
|
10
|
+
const perHour = (DECIMAL.test(text) ? Number(text) : NaN) * 60;
|
|
11
|
+
// The converted price must be finite: a minute price of 3e307 is a decimal and an infinite hourly price.
|
|
12
|
+
return Number.isFinite(perHour) ? { prices: { sessionUsdPerHour: perHour }, state: "priced" } : { prices: { sessionUsdPerHour: null }, state: "invalid" };
|
|
13
|
+
}
|
|
14
|
+
/** List prices with the host's overrides on top; an override of `null` is a deliberate gap. */
|
|
15
|
+
export const resolvePrices = (overrides = {}) => ({ ...LIST_PRICES, ...overrides });
|
|
16
|
+
export const toolUsage = (usd, state = "priced") => ({
|
|
17
|
+
usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: usd } },
|
|
18
|
+
state,
|
|
19
|
+
});
|
|
20
|
+
export const fetchUsage = (prices, proxied) => toolUsage(proxied ? prices.fetchProxiedUsd : prices.fetchUsd);
|
|
21
|
+
export const searchUsage = (prices) => toolUsage(prices.searchUsd);
|
|
22
|
+
/** Integer picodollars, so a bill reads as its decimal amount (0.002, not 0.0019999999999999996). */
|
|
23
|
+
const PICO = 1e12;
|
|
24
|
+
const HOUR_MS = 3600000n;
|
|
25
|
+
export const startSpent = (createdAt) => ({ seconds: 0, usd: 0, chargedThrough: createdAt });
|
|
26
|
+
/** `final` (the release) tops up to the provider's minimum and marks the record, so a retried release adds nothing. */
|
|
27
|
+
export function sessionCharge(spent, at, prices, state = "priced", final = false) {
|
|
28
|
+
if (spent.final)
|
|
29
|
+
return { spent, usage: toolUsage(0, state === "invalid" ? "invalid" : prices.sessionUsdPerHour === null || state !== "priced" ? "unpriced" : "priced") };
|
|
30
|
+
// Integer milliseconds, converted once: a session topped up to the minimum bills exactly the minimum, not
|
|
31
|
+
// 59.99999999999999 s.
|
|
32
|
+
const before = Math.round(spent.seconds * 1000);
|
|
33
|
+
const elapsed = Math.max(0, Date.parse(at) - Date.parse(spent.chargedThrough));
|
|
34
|
+
const charged = elapsed + (final ? Math.max(0, Math.round(prices.sessionMinimumS * 1000) - (before + elapsed)) : 0);
|
|
35
|
+
const price = prices.sessionUsdPerHour;
|
|
36
|
+
const priced = price !== null && state === "priced";
|
|
37
|
+
// Each charge bills its own milliseconds at the current price, in BigInt (the product passes 2^53 past about 75 s):
|
|
38
|
+
// whole picodollars go on the bill and the remainder is carried.
|
|
39
|
+
const owed = BigInt(charged) * (priced ? BigInt(Math.round(price * PICO)) : 0n) + BigInt(spent.carry ?? 0);
|
|
40
|
+
const picos = Number(owed / HOUR_MS);
|
|
41
|
+
const carry = Number(owed % HOUR_MS);
|
|
42
|
+
const gap = priced ? "priced" : state === "invalid" ? "invalid" : "unpriced";
|
|
43
|
+
return { spent: { seconds: (before + charged) / 1000, usd: (Math.round(spent.usd * PICO) + picos) / PICO, chargedThrough: elapsed > 0 ? at : spent.chargedThrough, ...(final ? { final: true } : {}), ...(carry ? { carry } : {}) }, usage: toolUsage(picos / PICO, gap) };
|
|
44
|
+
}
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
import type { Decisions, PageVerdict, WallClass } from "./decisions.js";
|
|
2
|
+
import { type EvidenceSink } from "./evidence.js";
|
|
3
|
+
import { type BrowserFailure } 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
|
+
/** Over 507 recorded pages, ordinary pages scored up to 0.66 and a page with a spliced instruction 0.98. */
|
|
9
|
+
export declare const INJECTION_THRESHOLD = 0.75;
|
|
10
|
+
/** The largest PDF handed to the host's `pdf.text`; a larger one is named and left to `format: "raw"`. */
|
|
11
|
+
export declare const PDF_TEXT_MAX_BYTES: number;
|
|
12
|
+
export declare const PDF_TEXT_TIMEOUT_MS = 120000;
|
|
13
|
+
/** Told the calling conversation's scope, so a host can hold it to what that conversation may use. `available`, when
|
|
14
|
+
* given, says whether that conversation can reach it at all: a backup it answers false for is neither tried nor named
|
|
15
|
+
* among the sources tried. */
|
|
16
|
+
export type WebBackup = {
|
|
17
|
+
name: string;
|
|
18
|
+
available?(scope: {
|
|
19
|
+
label: string;
|
|
20
|
+
proxies: boolean;
|
|
21
|
+
}): boolean;
|
|
22
|
+
fetch(url: string, signal?: AbortSignal, scope?: {
|
|
23
|
+
label: string;
|
|
24
|
+
proxies: boolean;
|
|
25
|
+
}): Promise<string>;
|
|
26
|
+
};
|
|
27
|
+
export type RenderedPage = {
|
|
28
|
+
finalUrl: string | null;
|
|
29
|
+
statusCode: number | null;
|
|
30
|
+
contentType: string | null;
|
|
31
|
+
content: string;
|
|
32
|
+
extractor?: "readability-md" | "inner-text";
|
|
33
|
+
usd?: number;
|
|
34
|
+
};
|
|
35
|
+
export type WebToolsOptions = {
|
|
36
|
+
/** `via` is `<name>_fetch` and `<name>_search`. */
|
|
37
|
+
name: string;
|
|
38
|
+
fetch?: (request: FetchRequest, signal?: AbortSignal) => Promise<FetchResult>;
|
|
39
|
+
search?: (request: SearchRequest, signal?: AbortSignal) => Promise<SearchResult>;
|
|
40
|
+
evidence: EvidenceSink;
|
|
41
|
+
scope(conversation: string | number): {
|
|
42
|
+
label: string;
|
|
43
|
+
proxies: boolean;
|
|
44
|
+
} | Promise<{
|
|
45
|
+
label: string;
|
|
46
|
+
proxies: boolean;
|
|
47
|
+
}>;
|
|
48
|
+
prices?: Partial<PriceTable>;
|
|
49
|
+
redact?: {
|
|
50
|
+
values: () => readonly string[];
|
|
51
|
+
};
|
|
52
|
+
backups?: readonly WebBackup[];
|
|
53
|
+
classifyPage?: Decisions["classifyPage"];
|
|
54
|
+
render?: {
|
|
55
|
+
enabled: boolean;
|
|
56
|
+
read(url: string, signal?: AbortSignal): Promise<RenderedPage>;
|
|
57
|
+
};
|
|
58
|
+
/** Text of a PDF the provider would not convert to markdown; null or blank is a PDF with no readable text. */
|
|
59
|
+
pdf?: {
|
|
60
|
+
text(bytes: Uint8Array, url: string, signal: AbortSignal): Promise<string | null>;
|
|
61
|
+
maxBytes?: number;
|
|
62
|
+
timeoutMs?: number;
|
|
63
|
+
};
|
|
64
|
+
};
|
|
65
|
+
export type Next = {
|
|
66
|
+
action: "drive_page" | "other_source";
|
|
67
|
+
note: string;
|
|
68
|
+
};
|
|
69
|
+
export type WebFailure = BrowserFailure & {
|
|
70
|
+
wall?: WallClass;
|
|
71
|
+
next?: Next;
|
|
72
|
+
};
|
|
73
|
+
export type WebOutcome = {
|
|
74
|
+
text: string;
|
|
75
|
+
isError: boolean;
|
|
76
|
+
details: Record<string, unknown>;
|
|
77
|
+
usd: number;
|
|
78
|
+
};
|
|
79
|
+
export declare const WALLS: Record<WallClass, {
|
|
80
|
+
code: "blocked" | "not_content";
|
|
81
|
+
what: string;
|
|
82
|
+
next: Next;
|
|
83
|
+
}>;
|
|
84
|
+
export declare const wallOf: (verdict: PageVerdict | null | undefined) => WallClass | null;
|
|
85
|
+
export declare function wallFailure(subject: string, wall: WallClass, detail?: string): WebFailure;
|
|
86
|
+
export declare function pageNotice(verdict: PageVerdict | null | undefined): string;
|
|
87
|
+
export declare function filedBody(result: string): string;
|
|
88
|
+
export type WebTools = {
|
|
89
|
+
fetch(conversation: string | number, args: {
|
|
90
|
+
url?: unknown;
|
|
91
|
+
format?: unknown;
|
|
92
|
+
}, signal?: AbortSignal): Promise<WebOutcome>;
|
|
93
|
+
search(conversation: string | number, args: {
|
|
94
|
+
query?: unknown;
|
|
95
|
+
n?: unknown;
|
|
96
|
+
}, signal?: AbortSignal): Promise<WebOutcome>;
|
|
97
|
+
};
|
|
98
|
+
export declare function createWebTools(options: WebToolsOptions): WebTools;
|