fastbrowse 0.0.0 → 0.5.20
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/LICENSE +21 -0
- package/README.md +48 -1
- package/dist/abort.d.ts +8 -0
- package/dist/abort.js +29 -0
- package/dist/binary.d.ts +14 -0
- package/dist/binary.js +58 -0
- package/dist/callbacks.d.ts +16 -0
- package/dist/callbacks.js +103 -0
- package/dist/errors.d.ts +26 -0
- package/dist/errors.js +40 -0
- package/dist/fastbrowse.d.ts +51 -0
- package/dist/fastbrowse.js +118 -0
- package/dist/index.d.ts +5 -0
- package/dist/index.js +3 -0
- package/dist/output.d.ts +76 -0
- package/dist/output.js +57 -0
- package/dist/protocol.d.ts +395 -0
- package/dist/protocol.js +26 -0
- package/dist/rpc.d.ts +18 -0
- package/dist/rpc.js +104 -0
- package/dist/run.d.ts +91 -0
- package/dist/run.js +63 -0
- package/package.json +33 -4
package/dist/output.js
ADDED
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
// The `output` option of `run`: the JSON Schema it puts on the wire, and the typed value it makes of the data
|
|
2
|
+
// that comes back.
|
|
3
|
+
import { FastbrowseError, messageOf } from './errors.js';
|
|
4
|
+
/** The extension a schema library implements to write itself as JSON Schema, by the name its specification has. */
|
|
5
|
+
const JSON_SCHEMA_EXTENSION = 'StandardJSONSchemaV1';
|
|
6
|
+
/** The draft `fastbrowse serve` reads. */
|
|
7
|
+
const TARGET = 'draft-2020-12';
|
|
8
|
+
/** The data of a run did not pass the `output` schema's own validation. */
|
|
9
|
+
export class OutputValidationError extends FastbrowseError {
|
|
10
|
+
/** The result as the server sent it, with the data that failed in `data`. */
|
|
11
|
+
result;
|
|
12
|
+
issues;
|
|
13
|
+
constructor(result, issues) {
|
|
14
|
+
super(`the data of the run does not match the output schema: ${issues.map(described).join('; ')}`);
|
|
15
|
+
this.result = result;
|
|
16
|
+
this.issues = issues;
|
|
17
|
+
}
|
|
18
|
+
}
|
|
19
|
+
function described(issue) {
|
|
20
|
+
const path = (issue.path ?? []).map(segment => String(typeof segment === 'object' ? segment.key : segment));
|
|
21
|
+
return path.length ? `${path.join('.')}: ${issue.message}` : issue.message;
|
|
22
|
+
}
|
|
23
|
+
function standard(schema) {
|
|
24
|
+
return schema['~standard'];
|
|
25
|
+
}
|
|
26
|
+
/** The JSON Schema that goes to the server as `output_schema`. */
|
|
27
|
+
export function wireSchema(schema) {
|
|
28
|
+
const props = standard(schema);
|
|
29
|
+
if (props === undefined)
|
|
30
|
+
return schema;
|
|
31
|
+
// Read as a value that may be missing: the types rule that out, and a caller's cast or plain JavaScript does not.
|
|
32
|
+
const convert = props.jsonSchema?.input;
|
|
33
|
+
if (typeof convert !== 'function') {
|
|
34
|
+
throw new FastbrowseError(`the output schema is a Standard Schema from "${props.vendor}" without the JSON Schema extension ` +
|
|
35
|
+
`(${JSON_SCHEMA_EXTENSION}, "~standard".jsonSchema), so there is no schema to send: use a version of ` +
|
|
36
|
+
'the library that has it or its JSON Schema adapter, or pass a JSON Schema object');
|
|
37
|
+
}
|
|
38
|
+
try {
|
|
39
|
+
return props.jsonSchema.input({ target: TARGET });
|
|
40
|
+
}
|
|
41
|
+
catch (error) {
|
|
42
|
+
throw new FastbrowseError(`the output schema cannot be written as JSON Schema: ${messageOf(error)}`, {
|
|
43
|
+
cause: error,
|
|
44
|
+
});
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
/** The result with its `output`. Rejects with `OutputValidationError` when the schema refuses the data. */
|
|
48
|
+
export async function withOutput(result, schema) {
|
|
49
|
+
const props = schema && standard(schema);
|
|
50
|
+
const unread = result.status !== 'complete' && result.data === null;
|
|
51
|
+
if (props === undefined || unread)
|
|
52
|
+
return { ...result, output: result.data };
|
|
53
|
+
const validation = await props.validate(result.data);
|
|
54
|
+
if (validation.issues)
|
|
55
|
+
throw new OutputValidationError(result, validation.issues);
|
|
56
|
+
return { ...result, output: validation.value };
|
|
57
|
+
}
|
|
@@ -0,0 +1,395 @@
|
|
|
1
|
+
export type ArtifactKind = 'download';
|
|
2
|
+
export type CostBasis = 'metered' | 'estimated' | 'unknown';
|
|
3
|
+
export type CostComponent = 'jev' | 'llm' | 'browser' | 'proxy';
|
|
4
|
+
export type LLMPurpose = 'plan' | 'read' | 'field_text' | 'recover' | 'verify' | 'compose' | 'shortcut';
|
|
5
|
+
/**
|
|
6
|
+
* The model whose choice a step carries out, even when code dispatches it: the next page of a list is the
|
|
7
|
+
* reader's, because the reader asked for the rest of the list.
|
|
8
|
+
*/
|
|
9
|
+
export type Decider = 'jev' | 'llm';
|
|
10
|
+
/**
|
|
11
|
+
* Every code an error reply can carry: the JSON-RPC standard ones, then this protocol's own.
|
|
12
|
+
*/
|
|
13
|
+
export type ErrorCode = -32700 | -32600 | -32601 | -32602 | -32603 | -32001 | -32002 | -32003 | -32004;
|
|
14
|
+
export type RequestId = number | string;
|
|
15
|
+
export type FactReader = 'jev_choice' | 'llm';
|
|
16
|
+
export type JsonValue = unknown;
|
|
17
|
+
/**
|
|
18
|
+
* What the server sends without being asked.
|
|
19
|
+
*/
|
|
20
|
+
export type ServerMethod = 'run/event' | 'run/frame' | 'run/until' | 'secrets/resolve';
|
|
21
|
+
export type Operation = 'click' | 'hover' | 'drag' | 'fill' | 'select' | 'enter' | 'escape' | 'scroll' | 'scroll_up' | 'back' | 'switch_tab' | 'upload' | 'dialog' | 'read' | 'done' | 'escalate' | 'navigate';
|
|
22
|
+
export type StepOutcome = 'executed' | 'covered' | 'stale' | 'failed';
|
|
23
|
+
export type Status = 'complete' | 'unverified' | 'needs_confirmation' | 'needs_login' | 'blocked' | 'needs_input' | 'stuck' | 'budget_exceeded' | 'observation_limit' | 'unavailable' | 'error';
|
|
24
|
+
export type Tripwire = 'no_progress' | 'action_repetition' | 'plan_stagnation';
|
|
25
|
+
export interface Artifact {
|
|
26
|
+
kind: ArtifactKind;
|
|
27
|
+
name: string;
|
|
28
|
+
mime_type: string;
|
|
29
|
+
size_bytes: number;
|
|
30
|
+
sha256: string;
|
|
31
|
+
/**
|
|
32
|
+
* Reference returned by the caller's `ArtifactSink`; fastbrowse never keeps bytes past the run.
|
|
33
|
+
*/
|
|
34
|
+
uri: string;
|
|
35
|
+
}
|
|
36
|
+
export interface Authorization {
|
|
37
|
+
/**
|
|
38
|
+
* Allow submit/pay/delete/send style actions without pausing for confirmation.
|
|
39
|
+
*/
|
|
40
|
+
irreversible_actions?: boolean;
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* Sent once, when the browser is open and before the first step.
|
|
44
|
+
*/
|
|
45
|
+
export interface BrowserEvent {
|
|
46
|
+
type: 'browser';
|
|
47
|
+
/**
|
|
48
|
+
* Where a cloud browser can be watched live; None for local Chrome.
|
|
49
|
+
*/
|
|
50
|
+
live_url: string | null;
|
|
51
|
+
/**
|
|
52
|
+
* The cloud browser's id, for a caller that may have to stop it out of band. None when the run did not
|
|
53
|
+
* start a browser of its own (local Chrome, or one handed over through `cdp_url`).
|
|
54
|
+
*/
|
|
55
|
+
browser_id: string | null;
|
|
56
|
+
}
|
|
57
|
+
export interface BudgetStop {
|
|
58
|
+
resource: 'steps' | 'dollars' | 'seconds' | 'jev_calls' | 'llm_calls';
|
|
59
|
+
limit: number;
|
|
60
|
+
}
|
|
61
|
+
export interface Citation {
|
|
62
|
+
/**
|
|
63
|
+
* The number used by this fact's links in the answer, stable within a run.
|
|
64
|
+
*/
|
|
65
|
+
id: number;
|
|
66
|
+
text: string;
|
|
67
|
+
requirement_id: string | null;
|
|
68
|
+
url: string;
|
|
69
|
+
quote: string;
|
|
70
|
+
deep_link: string;
|
|
71
|
+
}
|
|
72
|
+
export interface CostBreakdown {
|
|
73
|
+
lines: CostLine[];
|
|
74
|
+
}
|
|
75
|
+
export interface CostLine {
|
|
76
|
+
component: CostComponent;
|
|
77
|
+
basis: CostBasis;
|
|
78
|
+
dollars: number | null;
|
|
79
|
+
purpose: LLMPurpose | null;
|
|
80
|
+
input_tokens: number;
|
|
81
|
+
output_tokens: number;
|
|
82
|
+
/**
|
|
83
|
+
* Wall time of the call, retries included. None for a line that is not one call, such as browser time.
|
|
84
|
+
*/
|
|
85
|
+
seconds: number | null;
|
|
86
|
+
}
|
|
87
|
+
export interface Error {
|
|
88
|
+
code: ErrorCode;
|
|
89
|
+
message: string;
|
|
90
|
+
}
|
|
91
|
+
export interface ErrorResponse {
|
|
92
|
+
jsonrpc: '2.0';
|
|
93
|
+
id: RequestId | null;
|
|
94
|
+
error: Error;
|
|
95
|
+
}
|
|
96
|
+
export interface Evidence {
|
|
97
|
+
source_id: string;
|
|
98
|
+
url: string;
|
|
99
|
+
frame_id: string | null;
|
|
100
|
+
captured_at: string;
|
|
101
|
+
capture_sha256: string;
|
|
102
|
+
start: number;
|
|
103
|
+
end: number;
|
|
104
|
+
quote: string;
|
|
105
|
+
/**
|
|
106
|
+
* The quote covers an entire downloaded text file, apart from surrounding whitespace.
|
|
107
|
+
*/
|
|
108
|
+
complete_source: boolean;
|
|
109
|
+
control_context: SourceControl | null;
|
|
110
|
+
/**
|
|
111
|
+
* False for typed DOM observations whose quote is not literal rendered page text.
|
|
112
|
+
*/
|
|
113
|
+
rendered_text: boolean;
|
|
114
|
+
/**
|
|
115
|
+
* The headings the quote sits under on the page: which record a bare "£10.69" is the price of.
|
|
116
|
+
*/
|
|
117
|
+
heading_path: string[];
|
|
118
|
+
}
|
|
119
|
+
export interface SourceControl {
|
|
120
|
+
role: string;
|
|
121
|
+
label: string;
|
|
122
|
+
context: string | null;
|
|
123
|
+
}
|
|
124
|
+
/**
|
|
125
|
+
* The client's side of the handshake.
|
|
126
|
+
*
|
|
127
|
+
* Unknown fields are allowed here and nowhere else: a client on a later protocol may send some, and it has to
|
|
128
|
+
* get the server's version back to report the mismatch, which a refusal of its params would hide.
|
|
129
|
+
*/
|
|
130
|
+
export interface InitializeParams {
|
|
131
|
+
protocol_version: number;
|
|
132
|
+
}
|
|
133
|
+
export interface InitializeResult {
|
|
134
|
+
protocol_version: number;
|
|
135
|
+
fastbrowse_version: string;
|
|
136
|
+
}
|
|
137
|
+
export interface Limits {
|
|
138
|
+
/**
|
|
139
|
+
* Steps that reached the page. A click whose element was redrawn before it landed dispatched nothing and is
|
|
140
|
+
* not counted; the stall budget ends a page that keeps redrawing.
|
|
141
|
+
*/
|
|
142
|
+
max_steps?: number | null;
|
|
143
|
+
/**
|
|
144
|
+
* Logical Jev evaluations. A hedged or retried request adds cost but not a call.
|
|
145
|
+
*/
|
|
146
|
+
max_jev_calls?: number | null;
|
|
147
|
+
max_llm_calls?: number | null;
|
|
148
|
+
/**
|
|
149
|
+
* Bounds Jev and LLM spend as it happens. A cloud browser bills when it stops, after the run, so its
|
|
150
|
+
* cost is reported in the result but cannot stop the run that incurred it.
|
|
151
|
+
*/
|
|
152
|
+
max_dollars?: number | null;
|
|
153
|
+
/**
|
|
154
|
+
* Stops active work at the time budget. Returning also waits for owned request and browser cleanup.
|
|
155
|
+
*/
|
|
156
|
+
max_seconds?: number | null;
|
|
157
|
+
}
|
|
158
|
+
export interface LocalChrome {
|
|
159
|
+
/**
|
|
160
|
+
* A name or path that replaces discovery of the Chrome binary.
|
|
161
|
+
*/
|
|
162
|
+
binary?: string | null;
|
|
163
|
+
/**
|
|
164
|
+
* Show the window, to watch a run.
|
|
165
|
+
*/
|
|
166
|
+
headed?: boolean;
|
|
167
|
+
/**
|
|
168
|
+
* A profile directory kept between runs, so a site signed into there stays signed in. Without one,
|
|
169
|
+
* every run starts from a fresh profile that is deleted afterwards.
|
|
170
|
+
*/
|
|
171
|
+
profile?: string | null;
|
|
172
|
+
}
|
|
173
|
+
export interface NoParams {
|
|
174
|
+
}
|
|
175
|
+
/**
|
|
176
|
+
* A message from the server that takes no reply. It has no `id` member at all, which is what marks it.
|
|
177
|
+
*/
|
|
178
|
+
export interface Notification {
|
|
179
|
+
jsonrpc: '2.0';
|
|
180
|
+
method: ServerMethod;
|
|
181
|
+
params: unknown;
|
|
182
|
+
}
|
|
183
|
+
/**
|
|
184
|
+
* A method's params. An unknown field is refused, so a misspelled option is never dropped in silence.
|
|
185
|
+
*/
|
|
186
|
+
export interface Params {
|
|
187
|
+
}
|
|
188
|
+
/**
|
|
189
|
+
* A call in either direction. One without an id is a notification and gets no reply.
|
|
190
|
+
*/
|
|
191
|
+
export interface Request {
|
|
192
|
+
jsonrpc: '2.0';
|
|
193
|
+
id: RequestId | null;
|
|
194
|
+
method: string;
|
|
195
|
+
params: {
|
|
196
|
+
[k: string]: unknown;
|
|
197
|
+
} | unknown[] | null;
|
|
198
|
+
}
|
|
199
|
+
export interface Response {
|
|
200
|
+
jsonrpc: '2.0';
|
|
201
|
+
id: RequestId;
|
|
202
|
+
result: unknown;
|
|
203
|
+
}
|
|
204
|
+
/**
|
|
205
|
+
* An `Attachment` as it travels: JSON has no bytes, so the content is base64.
|
|
206
|
+
*/
|
|
207
|
+
export interface RunAttachment {
|
|
208
|
+
name: string;
|
|
209
|
+
mime_type: string;
|
|
210
|
+
content: string;
|
|
211
|
+
}
|
|
212
|
+
/**
|
|
213
|
+
* Which run to stop. One that is not active, because it finished or never was, is left as it is.
|
|
214
|
+
*
|
|
215
|
+
* The reply says only that the request was read. The run's own reply is what says it was cancelled: the
|
|
216
|
+
* `cancelled` error, written after its browser has closed.
|
|
217
|
+
*/
|
|
218
|
+
export interface RunCancelParams {
|
|
219
|
+
run_id: string;
|
|
220
|
+
}
|
|
221
|
+
/**
|
|
222
|
+
* The params of `run/event`: one thing a run did, written before that run's reply.
|
|
223
|
+
*/
|
|
224
|
+
export interface RunEvent {
|
|
225
|
+
run_id: string;
|
|
226
|
+
event: StepEvent | BrowserEvent;
|
|
227
|
+
}
|
|
228
|
+
export interface StepEvent {
|
|
229
|
+
type: 'step';
|
|
230
|
+
step: StepResult;
|
|
231
|
+
/**
|
|
232
|
+
* A PNG of the page this step acted on, when `Config.step_frames` asked for one. None when it did not,
|
|
233
|
+
* and also when a resolved secret was showing as page text: pixels cannot be masked the way text is.
|
|
234
|
+
*/
|
|
235
|
+
frame: string | null;
|
|
236
|
+
}
|
|
237
|
+
export interface StepResult {
|
|
238
|
+
index: number;
|
|
239
|
+
operation: Operation;
|
|
240
|
+
decided_by: Decider;
|
|
241
|
+
outcome: StepOutcome;
|
|
242
|
+
url: string;
|
|
243
|
+
/**
|
|
244
|
+
* Human-readable label of the chosen element; never contains a secret value.
|
|
245
|
+
*/
|
|
246
|
+
target: string | null;
|
|
247
|
+
confidence: number | null;
|
|
248
|
+
note: string | null;
|
|
249
|
+
/**
|
|
250
|
+
* Facts added to the notes by this step, with resolved secrets redacted.
|
|
251
|
+
*/
|
|
252
|
+
facts: StepFact[];
|
|
253
|
+
/**
|
|
254
|
+
* Whether the page's fingerprint changed; None for steps that do not act (read, escalate).
|
|
255
|
+
*/
|
|
256
|
+
page_changed: boolean | null;
|
|
257
|
+
duration_ms: number;
|
|
258
|
+
}
|
|
259
|
+
export interface StepFact {
|
|
260
|
+
text: string;
|
|
261
|
+
requirement_id: string | null;
|
|
262
|
+
/**
|
|
263
|
+
* None for a count, total or winner derived from other facts rather than read from the page.
|
|
264
|
+
*/
|
|
265
|
+
quote: string | null;
|
|
266
|
+
url: string | null;
|
|
267
|
+
reader: FactReader;
|
|
268
|
+
deep_link: string | null;
|
|
269
|
+
}
|
|
270
|
+
/**
|
|
271
|
+
* The params of `run/frame`: the active tab as it looked a moment ago. Sent only to a run that set `frames`.
|
|
272
|
+
*/
|
|
273
|
+
export interface RunFrame {
|
|
274
|
+
run_id: string;
|
|
275
|
+
frame: string;
|
|
276
|
+
}
|
|
277
|
+
/**
|
|
278
|
+
* One run. Apart from `run_id`, each field is the `run_task` argument or the CLI flag of the same name.
|
|
279
|
+
*
|
|
280
|
+
* The reply is the `RunResult`. No API key is among the fields: model and browser keys come from the
|
|
281
|
+
* environment the server inherited.
|
|
282
|
+
*/
|
|
283
|
+
export interface RunParams {
|
|
284
|
+
run_id: string;
|
|
285
|
+
task: string;
|
|
286
|
+
start?: string | null;
|
|
287
|
+
inputs?: {
|
|
288
|
+
[k: string]: string;
|
|
289
|
+
} | null;
|
|
290
|
+
attachments?: RunAttachment[];
|
|
291
|
+
limits?: Limits | null;
|
|
292
|
+
authorization?: Authorization | null;
|
|
293
|
+
output_schema?: {
|
|
294
|
+
[k: string]: unknown;
|
|
295
|
+
} | null;
|
|
296
|
+
secrets?: SecretRef[];
|
|
297
|
+
frames?: boolean;
|
|
298
|
+
until?: boolean;
|
|
299
|
+
downloads?: string | null;
|
|
300
|
+
record?: string | null;
|
|
301
|
+
cursor?: boolean;
|
|
302
|
+
local?: boolean;
|
|
303
|
+
chrome?: LocalChrome | null;
|
|
304
|
+
cloud_profile?: string | null;
|
|
305
|
+
cdp_url?: string | null;
|
|
306
|
+
cdp_port?: number | null;
|
|
307
|
+
attach?: boolean;
|
|
308
|
+
target_match?: string | null;
|
|
309
|
+
proxy_country?: string | null;
|
|
310
|
+
viewport?: [number, number] | null;
|
|
311
|
+
cloud_allow_resizing?: boolean;
|
|
312
|
+
}
|
|
313
|
+
export interface SecretRef {
|
|
314
|
+
name: string;
|
|
315
|
+
/**
|
|
316
|
+
* Origins (scheme://host[:port]) the value may be typed into; models only ever see `name`.
|
|
317
|
+
*/
|
|
318
|
+
origins: string[];
|
|
319
|
+
}
|
|
320
|
+
export interface RunResult {
|
|
321
|
+
status: Status;
|
|
322
|
+
budget: BudgetStop | null;
|
|
323
|
+
answer: string | null;
|
|
324
|
+
data: unknown;
|
|
325
|
+
evidence: Evidence[];
|
|
326
|
+
steps: StepResult[];
|
|
327
|
+
cost: CostBreakdown;
|
|
328
|
+
artifacts: Artifact[];
|
|
329
|
+
citations: Citation[];
|
|
330
|
+
error: string | null;
|
|
331
|
+
/**
|
|
332
|
+
* Where the browser was last observed; what a caller checks when the task was to arrive somewhere.
|
|
333
|
+
*/
|
|
334
|
+
final_url: string | null;
|
|
335
|
+
/**
|
|
336
|
+
* Shadow tripwires retain each occurrence so eval counts do not depend on logging configuration.
|
|
337
|
+
*/
|
|
338
|
+
would_fire: Tripwire[];
|
|
339
|
+
/**
|
|
340
|
+
* The videos this run finished writing, captioned then plain; empty when it recorded nothing or encoding failed.
|
|
341
|
+
*/
|
|
342
|
+
recordings: string[];
|
|
343
|
+
}
|
|
344
|
+
/**
|
|
345
|
+
* The params of `run/until`: the address a run ended on. The reply is a boolean, and false keeps the run
|
|
346
|
+
* from `complete`.
|
|
347
|
+
*/
|
|
348
|
+
export interface RunUntilParams {
|
|
349
|
+
run_id: string;
|
|
350
|
+
url: string;
|
|
351
|
+
}
|
|
352
|
+
/**
|
|
353
|
+
* The params of `secrets/resolve`: one value the run is about to type. The reply is the value, or null.
|
|
354
|
+
*/
|
|
355
|
+
export interface SecretsResolveParams {
|
|
356
|
+
run_id: string;
|
|
357
|
+
name: string;
|
|
358
|
+
origin: string;
|
|
359
|
+
}
|
|
360
|
+
/**
|
|
361
|
+
* A call from the server that the client answers, with a `Response` or an `ErrorResponse` carrying its id.
|
|
362
|
+
*
|
|
363
|
+
* The ids are the server's own and count up from one. A client's ids may be the same numbers: a reply is
|
|
364
|
+
* told from a request by having no `method`, so the two never meet.
|
|
365
|
+
*/
|
|
366
|
+
export interface ServerRequest {
|
|
367
|
+
jsonrpc: '2.0';
|
|
368
|
+
id: number;
|
|
369
|
+
method: ServerMethod;
|
|
370
|
+
params: unknown;
|
|
371
|
+
}
|
|
372
|
+
export declare const ErrorCode: {
|
|
373
|
+
readonly PARSE_ERROR: -32700;
|
|
374
|
+
readonly INVALID_REQUEST: -32600;
|
|
375
|
+
readonly METHOD_NOT_FOUND: -32601;
|
|
376
|
+
readonly INVALID_PARAMS: -32602;
|
|
377
|
+
readonly INTERNAL_ERROR: -32603;
|
|
378
|
+
readonly BUSY: -32001;
|
|
379
|
+
readonly CANCELLED: -32002;
|
|
380
|
+
readonly CONFIGURATION: -32003;
|
|
381
|
+
readonly UNSUPPORTED_SCHEMA: -32004;
|
|
382
|
+
};
|
|
383
|
+
export declare const Method: {
|
|
384
|
+
readonly INITIALIZE: 'initialize';
|
|
385
|
+
readonly RUN: 'run';
|
|
386
|
+
readonly RUN_CANCEL: 'run/cancel';
|
|
387
|
+
readonly SHUTDOWN: 'shutdown';
|
|
388
|
+
};
|
|
389
|
+
export declare const PROTOCOL_VERSION = 1;
|
|
390
|
+
export declare const ServerMethod: {
|
|
391
|
+
readonly RUN_EVENT: 'run/event';
|
|
392
|
+
readonly RUN_FRAME: 'run/frame';
|
|
393
|
+
readonly RUN_UNTIL: 'run/until';
|
|
394
|
+
readonly SECRETS_RESOLVE: 'secrets/resolve';
|
|
395
|
+
};
|
package/dist/protocol.js
ADDED
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
// Generated from the models in src/fastbrowse/protocol.py and src/fastbrowse/models.py.
|
|
2
|
+
// Do not edit: change the models, then run `npm run generate:sdk`.
|
|
3
|
+
export const ErrorCode = {
|
|
4
|
+
PARSE_ERROR: -32700,
|
|
5
|
+
INVALID_REQUEST: -32600,
|
|
6
|
+
METHOD_NOT_FOUND: -32601,
|
|
7
|
+
INVALID_PARAMS: -32602,
|
|
8
|
+
INTERNAL_ERROR: -32603,
|
|
9
|
+
BUSY: -32001,
|
|
10
|
+
CANCELLED: -32002,
|
|
11
|
+
CONFIGURATION: -32003,
|
|
12
|
+
UNSUPPORTED_SCHEMA: -32004,
|
|
13
|
+
};
|
|
14
|
+
export const Method = {
|
|
15
|
+
INITIALIZE: 'initialize',
|
|
16
|
+
RUN: 'run',
|
|
17
|
+
RUN_CANCEL: 'run/cancel',
|
|
18
|
+
SHUTDOWN: 'shutdown',
|
|
19
|
+
};
|
|
20
|
+
export const PROTOCOL_VERSION = 1;
|
|
21
|
+
export const ServerMethod = {
|
|
22
|
+
RUN_EVENT: 'run/event',
|
|
23
|
+
RUN_FRAME: 'run/frame',
|
|
24
|
+
RUN_UNTIL: 'run/until',
|
|
25
|
+
SECRETS_RESOLVE: 'secrets/resolve',
|
|
26
|
+
};
|
package/dist/rpc.d.ts
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import type { Readable, Writable } from 'node:stream';
|
|
2
|
+
type Params = Record<string, unknown>;
|
|
3
|
+
/** Answers a request the server makes. What it returns is the result, and what it throws is the error reply. */
|
|
4
|
+
export type RequestHandler = (params: Params) => unknown;
|
|
5
|
+
export type NotificationHandler = (params: Params) => void;
|
|
6
|
+
export declare class Connection {
|
|
7
|
+
#private;
|
|
8
|
+
constructor(input: Readable, output: Writable);
|
|
9
|
+
/** Call a method and wait for its reply. Rejects with `RpcError` when the server answers with an error. */
|
|
10
|
+
request(method: string, params?: object): Promise<unknown>;
|
|
11
|
+
notify(method: string, params?: Params): void;
|
|
12
|
+
/** Serve a method the server calls on this side. */
|
|
13
|
+
onRequest(method: string, handler: RequestHandler): void;
|
|
14
|
+
onNotification(method: string, handler: NotificationHandler): void;
|
|
15
|
+
/** The other side is gone. Every request still waiting rejects with `reason`, and so does any made later. */
|
|
16
|
+
end(reason: Error): void;
|
|
17
|
+
}
|
|
18
|
+
export {};
|
package/dist/rpc.js
ADDED
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
// JSON-RPC 2.0 over a pair of byte streams, one message per line. Both sides may call the other.
|
|
2
|
+
import { StringDecoder } from 'node:string_decoder';
|
|
3
|
+
import { FastbrowseError, messageOf, RpcError } from './errors.js';
|
|
4
|
+
import { ErrorCode } from './protocol.js';
|
|
5
|
+
export class Connection {
|
|
6
|
+
#output;
|
|
7
|
+
#pending = new Map();
|
|
8
|
+
#requests = new Map();
|
|
9
|
+
#notifications = new Map();
|
|
10
|
+
#nextId = 1;
|
|
11
|
+
#ended;
|
|
12
|
+
constructor(input, output) {
|
|
13
|
+
this.#output = output;
|
|
14
|
+
// A character can straddle two chunks, and decoding each chunk alone would break it.
|
|
15
|
+
const decoder = new StringDecoder('utf8');
|
|
16
|
+
let partial = '';
|
|
17
|
+
input.on('data', (chunk) => {
|
|
18
|
+
const lines = (partial + decoder.write(chunk)).split('\n');
|
|
19
|
+
partial = lines.pop() ?? '';
|
|
20
|
+
for (const line of lines)
|
|
21
|
+
this.#receive(line);
|
|
22
|
+
});
|
|
23
|
+
// A write to a server that has gone fails here. The request it carried is rejected by `end`, which the
|
|
24
|
+
// owner calls when the process exits, so the error has nothing more to say.
|
|
25
|
+
output.on('error', () => { });
|
|
26
|
+
}
|
|
27
|
+
/** Call a method and wait for its reply. Rejects with `RpcError` when the server answers with an error. */
|
|
28
|
+
request(method, params = {}) {
|
|
29
|
+
if (this.#ended)
|
|
30
|
+
return Promise.reject(this.#ended);
|
|
31
|
+
const id = this.#nextId++;
|
|
32
|
+
return new Promise((resolve, reject) => {
|
|
33
|
+
this.#pending.set(id, { resolve, reject });
|
|
34
|
+
this.#send({ id, method, params });
|
|
35
|
+
});
|
|
36
|
+
}
|
|
37
|
+
notify(method, params = {}) {
|
|
38
|
+
if (!this.#ended)
|
|
39
|
+
this.#send({ method, params });
|
|
40
|
+
}
|
|
41
|
+
/** Serve a method the server calls on this side. */
|
|
42
|
+
onRequest(method, handler) {
|
|
43
|
+
this.#requests.set(method, handler);
|
|
44
|
+
}
|
|
45
|
+
onNotification(method, handler) {
|
|
46
|
+
this.#notifications.set(method, handler);
|
|
47
|
+
}
|
|
48
|
+
/** The other side is gone. Every request still waiting rejects with `reason`, and so does any made later. */
|
|
49
|
+
end(reason) {
|
|
50
|
+
if (this.#ended)
|
|
51
|
+
return;
|
|
52
|
+
this.#ended = reason;
|
|
53
|
+
for (const pending of this.#pending.values())
|
|
54
|
+
pending.reject(reason);
|
|
55
|
+
this.#pending.clear();
|
|
56
|
+
}
|
|
57
|
+
#send(message) {
|
|
58
|
+
this.#output.write(`${JSON.stringify({ jsonrpc: '2.0', ...message })}\n`);
|
|
59
|
+
}
|
|
60
|
+
#receive(line) {
|
|
61
|
+
let message;
|
|
62
|
+
try {
|
|
63
|
+
message = JSON.parse(line);
|
|
64
|
+
}
|
|
65
|
+
catch {
|
|
66
|
+
// The server keeps everything but messages off this stream, so a line that is not one means the binary
|
|
67
|
+
// is not a fastbrowse server at all. Waiting on it would hang every request.
|
|
68
|
+
this.end(new FastbrowseError(`fastbrowse sent a line that is not JSON: ${line.slice(0, 200)}`));
|
|
69
|
+
return;
|
|
70
|
+
}
|
|
71
|
+
if (typeof message.method === 'string') {
|
|
72
|
+
void this.#serve(message.method, (message.params ?? {}), message.id);
|
|
73
|
+
return;
|
|
74
|
+
}
|
|
75
|
+
const pending = this.#pending.get(message.id);
|
|
76
|
+
if (!pending)
|
|
77
|
+
return;
|
|
78
|
+
this.#pending.delete(message.id);
|
|
79
|
+
if (message.error) {
|
|
80
|
+
const { code, message: text } = message.error;
|
|
81
|
+
pending.reject(new RpcError(code, text));
|
|
82
|
+
}
|
|
83
|
+
else {
|
|
84
|
+
pending.resolve(message.result);
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
async #serve(method, params, id) {
|
|
88
|
+
if (id === undefined) {
|
|
89
|
+
this.#notifications.get(method)?.(params);
|
|
90
|
+
return;
|
|
91
|
+
}
|
|
92
|
+
const handler = this.#requests.get(method);
|
|
93
|
+
if (!handler) {
|
|
94
|
+
this.#send({ id, error: { code: ErrorCode.METHOD_NOT_FOUND, message: `unknown method '${method}'` } });
|
|
95
|
+
return;
|
|
96
|
+
}
|
|
97
|
+
try {
|
|
98
|
+
this.#send({ id, result: (await handler(params)) ?? null });
|
|
99
|
+
}
|
|
100
|
+
catch (error) {
|
|
101
|
+
this.#send({ id, error: { code: ErrorCode.INTERNAL_ERROR, message: messageOf(error) } });
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
}
|
package/dist/run.d.ts
ADDED
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
import { type OutputSchema } from './output.ts';
|
|
2
|
+
import type { Authorization, BrowserEvent, Limits, LocalChrome, RunParams, SecretRef, StepEvent } from './protocol.ts';
|
|
3
|
+
type Camel<Name extends string> = Name extends `${infer Head}_${infer Tail}` ? `${Head}${Capitalize<Camel<Tail>>}` : Name;
|
|
4
|
+
/** A wire model with its field names in camelCase, so its fields follow the Python model without a second list. */
|
|
5
|
+
export type CamelKeys<Model> = {
|
|
6
|
+
[Name in keyof Model as Camel<Name & string>]: Model[Name];
|
|
7
|
+
};
|
|
8
|
+
/** Which browser a run drives. Given to `Fastbrowse.start`, these are the defaults of every run it makes. */
|
|
9
|
+
export interface BrowserOptions {
|
|
10
|
+
/** Local Chrome instead of a Browser Use Cloud browser. */
|
|
11
|
+
local?: boolean;
|
|
12
|
+
/** Which local Chrome, and how. A headed window or a kept profile implies `local`. */
|
|
13
|
+
chrome?: CamelKeys<LocalChrome>;
|
|
14
|
+
cloudProfile?: string;
|
|
15
|
+
/** The DevTools WebSocket URL of a browser that is already running. The run neither starts nor stops it. */
|
|
16
|
+
cdpUrl?: string;
|
|
17
|
+
/** The DevTools port of a browser that is already running on this machine. */
|
|
18
|
+
cdpPort?: number;
|
|
19
|
+
/** Drive a window that is already open in the browser `cdpUrl` or `cdpPort` names, and open no tab. */
|
|
20
|
+
attach?: boolean;
|
|
21
|
+
/** Part of the URL or title of the window to attach to. */
|
|
22
|
+
targetMatch?: string;
|
|
23
|
+
/** The two-letter country a cloud browser browses from. */
|
|
24
|
+
proxyCountry?: string;
|
|
25
|
+
viewport?: [width: number, height: number];
|
|
26
|
+
cloudAllowResizing?: boolean;
|
|
27
|
+
}
|
|
28
|
+
export interface Attachment {
|
|
29
|
+
name: string;
|
|
30
|
+
mimeType: string;
|
|
31
|
+
content: Uint8Array;
|
|
32
|
+
}
|
|
33
|
+
/** The secrets a run may type. The server and the models see the refs, and the values stay with `resolve`. */
|
|
34
|
+
export interface Secrets {
|
|
35
|
+
refs: SecretRef[];
|
|
36
|
+
/**
|
|
37
|
+
* The value of the secret `name`, about to be typed on `origin`, or nothing when there is none. Called each
|
|
38
|
+
* time a value is typed and never for an origin the ref does not cover, so a one-time code is computed
|
|
39
|
+
* when it is needed. If it throws, the run ends with status `error`, and what it threw is left out of the
|
|
40
|
+
* result.
|
|
41
|
+
*/
|
|
42
|
+
resolve: (name: string, origin: string) => MaybePromise<string | null | undefined>;
|
|
43
|
+
}
|
|
44
|
+
type MaybePromise<Value> = Value | Promise<Value>;
|
|
45
|
+
/**
|
|
46
|
+
* Each option as one run may give it. Null takes the default `Fastbrowse.start` was given out of that run:
|
|
47
|
+
* a default `cdpPort` has to go before the run can ask for `local`, and leaving the option out keeps it.
|
|
48
|
+
*/
|
|
49
|
+
export type PerRun<Options> = {
|
|
50
|
+
[Name in keyof Options]?: Options[Name] | null;
|
|
51
|
+
};
|
|
52
|
+
export interface RunOptions extends PerRun<BrowserOptions> {
|
|
53
|
+
/** The address to start on. Without one, the first address is proposed from the task. */
|
|
54
|
+
start?: string;
|
|
55
|
+
inputs?: Record<string, string>;
|
|
56
|
+
/** Files the run may upload. */
|
|
57
|
+
attachments?: Attachment[];
|
|
58
|
+
limits?: CamelKeys<Limits>;
|
|
59
|
+
authorization?: CamelKeys<Authorization>;
|
|
60
|
+
/**
|
|
61
|
+
* The shape of the data to read: a Zod, ArkType or other Standard Schema that can write itself as JSON
|
|
62
|
+
* Schema, or a JSON Schema object. The first also validates what comes back, and types `output`.
|
|
63
|
+
*/
|
|
64
|
+
output?: OutputSchema;
|
|
65
|
+
/** A directory that keeps the files the run downloads. */
|
|
66
|
+
downloads?: string;
|
|
67
|
+
/** Where to write a video of the run. The server needs ffmpeg for it. */
|
|
68
|
+
record?: string;
|
|
69
|
+
/** Draw visual cursor feedback for visible local Chrome on Linux X11 with Cua Driver. */
|
|
70
|
+
cursor?: boolean;
|
|
71
|
+
secrets?: Secrets;
|
|
72
|
+
/** Called with the address the run ended on. Anything but true keeps the run from `complete`. */
|
|
73
|
+
until?: (url: string) => MaybePromise<boolean>;
|
|
74
|
+
/**
|
|
75
|
+
* Called with the browser event and then each step event, in the order the run produced them. Like any
|
|
76
|
+
* callback here, one that throws or rejects ends the run with status `error`.
|
|
77
|
+
*/
|
|
78
|
+
onEvent?: (event: StepEvent | BrowserEvent) => void;
|
|
79
|
+
/** Called with JPEG frames of the active tab while the run goes on. Without it the page is never filmed. */
|
|
80
|
+
onFrame?: (frame: Uint8Array) => void;
|
|
81
|
+
/**
|
|
82
|
+
* Stops the run when it aborts. `run` then rejects with `AbortError`, after the run's browser has closed.
|
|
83
|
+
* A signal that has already aborted starts no run.
|
|
84
|
+
*/
|
|
85
|
+
signal?: AbortSignal;
|
|
86
|
+
}
|
|
87
|
+
/** The browser every run of an instance uses, as the fields of a `run` request. */
|
|
88
|
+
export declare function browserParams(options: BrowserOptions): Partial<RunParams>;
|
|
89
|
+
/** The `run` request for a task: the defaults from `start`, then this run's own options over them. */
|
|
90
|
+
export declare function runParams(runId: string, task: string, defaults: Partial<RunParams>, options: RunOptions): RunParams;
|
|
91
|
+
export {};
|