fastbrowse 0.9.1 → 0.11.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +35 -9
- package/dist/abort.d.ts +2 -2
- package/dist/abort.js +3 -3
- package/dist/addon.d.ts +11 -1
- package/dist/addon.js +17 -2
- package/dist/callbacks.d.ts +2 -2
- package/dist/callbacks.js +12 -7
- package/dist/errors.d.ts +10 -2
- package/dist/errors.js +11 -2
- package/dist/fastbrowse.d.ts +1 -1
- package/dist/fastbrowse.js +4 -3
- package/dist/index.d.ts +1 -1
- package/dist/protocol.d.ts +165 -81
- package/dist/protocol.js +1 -1
- package/dist/rpc.d.ts +0 -1
- package/dist/rpc.js +2 -6
- package/dist/run.d.ts +36 -9
- package/dist/run.js +11 -2
- package/package.json +6 -6
package/README.md
CHANGED
|
@@ -8,20 +8,19 @@ a native binary, so the machine needs no Python.
|
|
|
8
8
|
|
|
9
9
|
```sh
|
|
10
10
|
npm install fastbrowse
|
|
11
|
-
export TYPESAFE_API_KEY=...
|
|
12
11
|
export OPENROUTER_API_KEY=...
|
|
13
12
|
```
|
|
14
13
|
|
|
15
|
-
`
|
|
16
|
-
|
|
17
|
-
the LLM uses `AI_GATEWAY_API_KEY`.
|
|
14
|
+
`OPENROUTER_API_KEY` is the recommended route for Jev and the LLM. Without it, the LLM uses `AI_GATEWAY_API_KEY`
|
|
15
|
+
and Jev uses `TYPESAFE_API_KEY` when set.
|
|
18
16
|
|
|
19
17
|
With it npm installs the binary for your platform as an optional dependency: `@fastbrowse/darwin-arm64`,
|
|
20
18
|
`darwin-x64`, `linux-arm64`, `linux-x64` or `win32-x64`. No install script runs and nothing is downloaded on
|
|
21
19
|
first use. It needs Node.js 20 or newer, and on Linux it needs glibc.
|
|
22
20
|
|
|
23
|
-
The binary brings no browser. `local: true` drives
|
|
24
|
-
|
|
21
|
+
The binary brings no browser. `local: true` drives your own Chrome through the
|
|
22
|
+
[fastbrowse extension](../../docs/cli.md#your-own-chrome), signed in as you are; add `launch: true` to start a separate
|
|
23
|
+
Chrome instead. Without either a run starts a Browser Use Cloud browser, which needs `BROWSER_USE_API_KEY`.
|
|
25
24
|
|
|
26
25
|
## First run
|
|
27
26
|
|
|
@@ -52,17 +51,33 @@ stopped it in `result.wall`: `kind` is `password`, `one_time_code`, `sign_in` or
|
|
|
52
51
|
a second `run` while one is active rejects with the busy error, so start more instances to run side by side.
|
|
53
52
|
`close()` shuts the process down and waits for it, and the process also exits when yours does.
|
|
54
53
|
|
|
54
|
+
`Fastbrowse.start({ inProcess: true })` runs on the native addon in your Node process. PDF reading still uses a
|
|
55
|
+
helper binary, selected by `binaryPath`, then `FASTBROWSE_BINARY`, then the installed platform package. Keep the
|
|
56
|
+
addon and helper on matching fastbrowse versions.
|
|
57
|
+
|
|
55
58
|
`run` rejects when no run took place or none finished: with `RpcError` when the server refuses the request before
|
|
56
59
|
a browser opens (a bad option, a missing key, a busy server), with `AbortError` when `signal` stopped the run, and
|
|
57
60
|
with `ProcessExitedError` when the process is gone. It also rejects with `OutputValidationError` when a run
|
|
58
61
|
finished but its data fails the `output` schema. A run that fails after it starts, including one whose
|
|
59
62
|
callback throws, resolves with status `error`.
|
|
60
63
|
|
|
64
|
+
Jev cost lines include `decision_purpose` when the agent named the decision: `action`, `authorization`,
|
|
65
|
+
`relevance`, `read`, `verify` or `locate`. LLM lines keep their existing `purpose`. An unscoped decision
|
|
66
|
+
client call omits the optional field, and older receipts remain readable.
|
|
67
|
+
|
|
68
|
+
An `AbortError` carries `receipt` once the server has closed the browser: the steps it reported, known cost
|
|
69
|
+
lines and finished recordings. A cancelled `RpcError` carries the same receipt. A cancellation before the run
|
|
70
|
+
starts has none. The receipt has no status or answer, and an unpriced charge remains `unknown`.
|
|
71
|
+
|
|
61
72
|
## Options
|
|
62
73
|
|
|
63
74
|
The result is the `RunResult` the Python library returns. Its fields keep their Python names, such as
|
|
64
75
|
`final_url`, since the types are generated from the protocol's schema; the options are camelCase.
|
|
65
76
|
|
|
77
|
+
A safe final screenshot is returned in `result.artifacts` with `kind: "screenshot"`, `mime_type: "image/png"`,
|
|
78
|
+
a SHA-256 digest and a base64 data URI in `uri`. A task can request the screenshot without enabling step frames.
|
|
79
|
+
If a resolved secret is visible, the image is withheld.
|
|
80
|
+
|
|
66
81
|
`output` is `data` after a Zod (4.2 or newer) or ArkType schema's validation and transforms, or a Valibot schema
|
|
67
82
|
wrapped by `@valibot/to-json-schema`, typed as the schema's output. Data the schema refuses rejects with
|
|
68
83
|
`OutputValidationError`, which carries the result. A plain JSON Schema object is accepted too; `output` is then
|
|
@@ -70,11 +85,22 @@ wrapped by `@valibot/to-json-schema`, typed as the schema's output. Data the sch
|
|
|
70
85
|
any other keyword by name, but a run fills only a flat object of required string, number, integer and boolean
|
|
71
86
|
fields. With any other field it ends `unverified` with no data.
|
|
72
87
|
|
|
73
|
-
`run` also takes `context`, `inputs`, `attachments` as bytes, `downloads`, `record`, `onFrame` (JPEG frames of the
|
|
88
|
+
`run` also takes `context`, `inputs`, `attachments` as bytes, `downloads`, `record`, `recipe`, `saveRecipe`, `onFrame` (JPEG frames of the
|
|
74
89
|
active tab; none are sent without it), and the browser choices `chrome`, `cloudProfile`, `cdpUrl`, `cdpPort`,
|
|
75
|
-
`attach`, `targetMatch`, `foreground`, `proxyCountry`, `viewport` and `
|
|
76
|
-
takes the browser choices as defaults for every run, and a run passes `null` for one to go
|
|
90
|
+
`attach`, `targetMatch`, `foreground`, `proxyCountry`, `viewport`, `cloudExtensions` and `cloudTimeoutMinutes`.
|
|
91
|
+
`Fastbrowse.start` takes the browser choices as defaults for every run, and a run passes `null` for one to go
|
|
92
|
+
without that default.
|
|
93
|
+
|
|
94
|
+
A run reads pages over HTTP until the task needs a browser. `fetch: true` never starts one, and `browser: true`
|
|
95
|
+
starts one from the first step; the server refuses the two together. `allowedOrigins` limits the documents a run
|
|
96
|
+
may open, read and control to those exact origins: navigations, redirects, frames and popups elsewhere are refused
|
|
97
|
+
before they are sent, so a sign-in that redirects through another origin needs it listed too. It scopes documents,
|
|
98
|
+
not the network, and a scoped run sends no frames and cannot `record`.
|
|
99
|
+
Set `EXA_API_KEY` in the server environment to offer browserless web search. Jev picks among LLM-proposed queries;
|
|
100
|
+
result fields become citable records and links use the same origin checks. Search charges appear under `search`.
|
|
77
101
|
`env` in `Fastbrowse.start` adds to the environment the process inherits.
|
|
102
|
+
Recipe paths name files on the server running fastbrowse. `saveRecipe` writes after a completed run; a write failure is logged without changing the task status, so check the file before replay;
|
|
103
|
+
`recipe` reuses saved values for matching live actions with the same task.
|
|
78
104
|
|
|
79
105
|
## Platforms
|
|
80
106
|
|
package/dist/abort.d.ts
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* Make the `run` request with `send`, and call `cancel` if `signal` aborts while it is waiting on its reply.
|
|
3
3
|
*
|
|
4
4
|
* The server answers a cancelled run with the `cancelled` error once the run's browser has closed, and that
|
|
5
|
-
* reply is what rejects with `AbortError
|
|
6
|
-
* with its result.
|
|
5
|
+
* reply is what rejects with `AbortError`, carrying the receipt of what the run did and spent. A run that
|
|
6
|
+
* finished before the cancellation reached it resolves with its result.
|
|
7
7
|
*/
|
|
8
8
|
export declare function abortable<Result>(signal: AbortSignal | undefined, send: () => Promise<Result>, cancel: () => void): Promise<Result>;
|
package/dist/abort.js
CHANGED
|
@@ -5,8 +5,8 @@ import { ErrorCode } from './protocol.js';
|
|
|
5
5
|
* Make the `run` request with `send`, and call `cancel` if `signal` aborts while it is waiting on its reply.
|
|
6
6
|
*
|
|
7
7
|
* The server answers a cancelled run with the `cancelled` error once the run's browser has closed, and that
|
|
8
|
-
* reply is what rejects with `AbortError
|
|
9
|
-
* with its result.
|
|
8
|
+
* reply is what rejects with `AbortError`, carrying the receipt of what the run did and spent. A run that
|
|
9
|
+
* finished before the cancellation reached it resolves with its result.
|
|
10
10
|
*/
|
|
11
11
|
export async function abortable(signal, send, cancel) {
|
|
12
12
|
if (!signal)
|
|
@@ -20,7 +20,7 @@ export async function abortable(signal, send, cancel) {
|
|
|
20
20
|
catch (error) {
|
|
21
21
|
// `shutdown` cancels a run too, and that one the caller did not abort.
|
|
22
22
|
if (signal.aborted && error instanceof RpcError && error.code === ErrorCode.CANCELLED)
|
|
23
|
-
throw new AbortError(signal.reason);
|
|
23
|
+
throw new AbortError(signal.reason, error.receipt);
|
|
24
24
|
throw error;
|
|
25
25
|
}
|
|
26
26
|
finally {
|
package/dist/addon.d.ts
CHANGED
|
@@ -14,18 +14,28 @@ interface AddonCancel {
|
|
|
14
14
|
/** What `crates/fastbrowse-node` exports. */
|
|
15
15
|
export interface Addon {
|
|
16
16
|
Core: new (env?: Record<string, string>) => {
|
|
17
|
-
/** Resolves with `{"result": RunResult}` or `{"error": {"code", "message"}}` as JSON. */
|
|
17
|
+
/** Resolves with `{"result": RunResult}` or `{"error": {"code", "message", "data"?}}` as JSON. */
|
|
18
18
|
runTask(params: string, host?: AddonHost, cancel?: AddonCancel): Promise<string>;
|
|
19
19
|
};
|
|
20
20
|
RunCancel: new () => AddonCancel;
|
|
21
21
|
version(): string;
|
|
22
22
|
protocolVersion(): number;
|
|
23
|
+
/**
|
|
24
|
+
* Read PDFs by running this fastbrowse binary as a helper process. False when a helper was already set.
|
|
25
|
+
*/
|
|
26
|
+
setPdfHelper(path: string): boolean;
|
|
23
27
|
}
|
|
24
28
|
/**
|
|
25
29
|
* The addon to load: the caller's own path first, then the one the environment names, then the `fastbrowse.node`
|
|
26
30
|
* beside the binary in the platform package.
|
|
27
31
|
*/
|
|
28
32
|
export declare function loadAddon(addonPath: string | undefined, env: NodeJS.ProcessEnv): Addon;
|
|
33
|
+
/**
|
|
34
|
+
* Have `addon` read PDFs with the fastbrowse binary `env` resolves to, once its protocol is known to match. A PDF is
|
|
35
|
+
* read in a process the run can kill, and Node is no program the addon can run again for that: the binary beside it
|
|
36
|
+
* is. Without a binary, the addon still runs and says of each PDF that its text went unread.
|
|
37
|
+
*/
|
|
38
|
+
export declare function readPdfsWith(addon: Addon, env: NodeJS.ProcessEnv, binaryPath?: string): void;
|
|
29
39
|
/** Runs on the addon, one at a time as the fastbrowse process runs them, so the two modes answer alike. */
|
|
30
40
|
export declare class InProcess {
|
|
31
41
|
#private;
|
package/dist/addon.js
CHANGED
|
@@ -4,7 +4,7 @@ import { createRequire } from 'node:module';
|
|
|
4
4
|
import { dirname, join } from 'node:path';
|
|
5
5
|
import { Callbacks } from './callbacks.js';
|
|
6
6
|
import { abortable } from './abort.js';
|
|
7
|
-
import { platformPackage } from './binary.js';
|
|
7
|
+
import { platformPackage, resolveBinary } from './binary.js';
|
|
8
8
|
import { FastbrowseError, messageOf, RpcError } from './errors.js';
|
|
9
9
|
import { ErrorCode } from './protocol.js';
|
|
10
10
|
/**
|
|
@@ -22,6 +22,21 @@ export function loadAddon(addonPath, env) {
|
|
|
22
22
|
});
|
|
23
23
|
}
|
|
24
24
|
}
|
|
25
|
+
/**
|
|
26
|
+
* Have `addon` read PDFs with the fastbrowse binary `env` resolves to, once its protocol is known to match. A PDF is
|
|
27
|
+
* read in a process the run can kill, and Node is no program the addon can run again for that: the binary beside it
|
|
28
|
+
* is. Without a binary, the addon still runs and says of each PDF that its text went unread.
|
|
29
|
+
*/
|
|
30
|
+
export function readPdfsWith(addon, env, binaryPath) {
|
|
31
|
+
let binary;
|
|
32
|
+
try {
|
|
33
|
+
binary = resolveBinary(binaryPath, env);
|
|
34
|
+
}
|
|
35
|
+
catch {
|
|
36
|
+
return;
|
|
37
|
+
}
|
|
38
|
+
addon.setPdfHelper(binary);
|
|
39
|
+
}
|
|
25
40
|
/** The JSON a host function answers with. What a callback threw reaches the core as its message alone. */
|
|
26
41
|
async function answered(call) {
|
|
27
42
|
try {
|
|
@@ -74,7 +89,7 @@ export class InProcess {
|
|
|
74
89
|
this.#active = undefined;
|
|
75
90
|
}
|
|
76
91
|
if (reply.error)
|
|
77
|
-
throw new RpcError(reply.error.code, reply.error.message);
|
|
92
|
+
throw new RpcError(reply.error.code, reply.error.message, reply.error.data ?? undefined);
|
|
78
93
|
return reply.result;
|
|
79
94
|
};
|
|
80
95
|
const stop = () => cancel.cancel();
|
package/dist/callbacks.d.ts
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
|
-
import { type BrowserEvent, type RunResult, type StepEvent } from './protocol.ts';
|
|
1
|
+
import { type BrowserEvent, type BrowserWarningEvent, type RunResult, type StepEvent } from './protocol.ts';
|
|
2
2
|
import type { Connection } from './rpc.ts';
|
|
3
3
|
import type { RunOptions } from './run.ts';
|
|
4
4
|
export declare class Callbacks {
|
|
5
5
|
#private;
|
|
6
6
|
/** Without a connection, the in-process core calls the four methods below itself. */
|
|
7
7
|
constructor(connection?: Connection);
|
|
8
|
-
event(runId: string, event: StepEvent | BrowserEvent): void;
|
|
8
|
+
event(runId: string, event: StepEvent | BrowserEvent | BrowserWarningEvent): void;
|
|
9
9
|
frame(runId: string, jpeg: Uint8Array): void;
|
|
10
10
|
until(runId: string, url: string): Promise<boolean>;
|
|
11
11
|
resolve(runId: string, name: string, origin: string): Promise<string | null>;
|
package/dist/callbacks.js
CHANGED
|
@@ -59,11 +59,11 @@ export class Callbacks {
|
|
|
59
59
|
try {
|
|
60
60
|
const result = await run();
|
|
61
61
|
// A run can finish before the cancellation reaches it, and its callback failed all the same.
|
|
62
|
-
return served.failure === undefined ? result : endedBy(served.failure);
|
|
62
|
+
return served.failure === undefined ? result : endedBy(served.failure, result);
|
|
63
63
|
}
|
|
64
64
|
catch (error) {
|
|
65
65
|
if (served.failure !== undefined && error instanceof RpcError && error.code === ErrorCode.CANCELLED) {
|
|
66
|
-
return endedBy(served.failure);
|
|
66
|
+
return endedBy(served.failure, error.receipt);
|
|
67
67
|
}
|
|
68
68
|
throw error;
|
|
69
69
|
}
|
|
@@ -97,21 +97,26 @@ export class Callbacks {
|
|
|
97
97
|
return callback;
|
|
98
98
|
}
|
|
99
99
|
}
|
|
100
|
-
/**
|
|
101
|
-
|
|
100
|
+
/**
|
|
101
|
+
* The result of a run that a throwing callback ended, in the shape the server gives one, with the steps, cost
|
|
102
|
+
* and videos of what it did: its receipt, or its own result when it finished before the cancellation reached it.
|
|
103
|
+
*/
|
|
104
|
+
function endedBy(failure, spent) {
|
|
102
105
|
return {
|
|
103
106
|
status: 'error',
|
|
104
107
|
budget: null,
|
|
105
108
|
answer: null,
|
|
106
109
|
data: null,
|
|
107
110
|
evidence: [],
|
|
108
|
-
steps: [],
|
|
109
|
-
cost: { lines: [] },
|
|
111
|
+
steps: spent?.steps ?? [],
|
|
112
|
+
cost: spent?.cost ?? { lines: [] },
|
|
110
113
|
artifacts: [],
|
|
111
114
|
citations: [],
|
|
112
115
|
error: failure,
|
|
116
|
+
failure_kind: null,
|
|
113
117
|
final_url: null,
|
|
114
|
-
recordings: [],
|
|
118
|
+
recordings: spent?.recordings ?? [],
|
|
115
119
|
wall: null,
|
|
120
|
+
browser: spent?.browser ?? null,
|
|
116
121
|
};
|
|
117
122
|
}
|
package/dist/errors.d.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import type { CancellationReceipt } from './protocol.ts';
|
|
1
2
|
/** Every error this package throws, so one `instanceof` tells its failures from the caller's own. */
|
|
2
3
|
export declare class FastbrowseError extends Error {
|
|
3
4
|
constructor(message: string, options?: ErrorOptions);
|
|
@@ -15,12 +16,19 @@ export declare class ProcessExitedError extends FastbrowseError {
|
|
|
15
16
|
* is a `TimeoutError`.
|
|
16
17
|
*/
|
|
17
18
|
export declare class AbortError extends FastbrowseError {
|
|
18
|
-
|
|
19
|
+
/**
|
|
20
|
+
* What the run did and spent before it stopped. Undefined when no run started, or when the server sent no
|
|
21
|
+
* receipt.
|
|
22
|
+
*/
|
|
23
|
+
readonly receipt: CancellationReceipt | undefined;
|
|
24
|
+
constructor(reason: unknown, receipt?: CancellationReceipt);
|
|
19
25
|
}
|
|
20
26
|
/** What a thrown value says. A callback is the caller's code, and it can throw anything. */
|
|
21
27
|
export declare function messageOf(thrown: unknown): string;
|
|
22
28
|
/** The server's error reply to a request. `code` is one of the protocol's error codes. */
|
|
23
29
|
export declare class RpcError extends FastbrowseError {
|
|
24
30
|
readonly code: number;
|
|
25
|
-
|
|
31
|
+
/** On the `cancelled` error, what the run did and spent before it stopped; undefined on every other. */
|
|
32
|
+
readonly receipt: CancellationReceipt | undefined;
|
|
33
|
+
constructor(code: number, message: string, receipt?: CancellationReceipt);
|
|
26
34
|
}
|
package/dist/errors.js
CHANGED
|
@@ -22,8 +22,14 @@ export class ProcessExitedError extends FastbrowseError {
|
|
|
22
22
|
* is a `TimeoutError`.
|
|
23
23
|
*/
|
|
24
24
|
export class AbortError extends FastbrowseError {
|
|
25
|
-
|
|
25
|
+
/**
|
|
26
|
+
* What the run did and spent before it stopped. Undefined when no run started, or when the server sent no
|
|
27
|
+
* receipt.
|
|
28
|
+
*/
|
|
29
|
+
receipt;
|
|
30
|
+
constructor(reason, receipt) {
|
|
26
31
|
super('the run was aborted', { cause: reason });
|
|
32
|
+
this.receipt = receipt;
|
|
27
33
|
}
|
|
28
34
|
}
|
|
29
35
|
/** What a thrown value says. A callback is the caller's code, and it can throw anything. */
|
|
@@ -33,8 +39,11 @@ export function messageOf(thrown) {
|
|
|
33
39
|
/** The server's error reply to a request. `code` is one of the protocol's error codes. */
|
|
34
40
|
export class RpcError extends FastbrowseError {
|
|
35
41
|
code;
|
|
36
|
-
|
|
42
|
+
/** On the `cancelled` error, what the run did and spent before it stopped; undefined on every other. */
|
|
43
|
+
receipt;
|
|
44
|
+
constructor(code, message, receipt) {
|
|
37
45
|
super(message);
|
|
38
46
|
this.code = code;
|
|
47
|
+
this.receipt = receipt;
|
|
39
48
|
}
|
|
40
49
|
}
|
package/dist/fastbrowse.d.ts
CHANGED
|
@@ -18,7 +18,7 @@ export interface StartOptions extends BrowserOptions {
|
|
|
18
18
|
/**
|
|
19
19
|
* Run the agent inside this process, on the fastbrowse addon, instead of starting a fastbrowse process. Runs
|
|
20
20
|
* and their results are the same; `env` then adds to the environment the settings are read from, and
|
|
21
|
-
* `binaryPath`
|
|
21
|
+
* `binaryPath` selects its PDF helper process; `stderr` has no effect.
|
|
22
22
|
*/
|
|
23
23
|
inProcess?: boolean;
|
|
24
24
|
/**
|
package/dist/fastbrowse.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { spawn } from 'node:child_process';
|
|
2
2
|
import { randomUUID } from 'node:crypto';
|
|
3
3
|
import { abortable } from './abort.js';
|
|
4
|
-
import { InProcess, loadAddon } from './addon.js';
|
|
4
|
+
import { InProcess, loadAddon, readPdfsWith } from './addon.js';
|
|
5
5
|
import { Callbacks } from './callbacks.js';
|
|
6
6
|
import { resolveBinary } from './binary.js';
|
|
7
7
|
import { FastbrowseError, ProcessExitedError } from './errors.js';
|
|
@@ -31,14 +31,15 @@ export class Fastbrowse {
|
|
|
31
31
|
* addon instead and run in this process.
|
|
32
32
|
*/
|
|
33
33
|
static async start(options = {}) {
|
|
34
|
+
const env = { ...process.env, ...options.env };
|
|
34
35
|
if (options.inProcess) {
|
|
35
|
-
const addon = loadAddon(options.addonPath,
|
|
36
|
+
const addon = loadAddon(options.addonPath, env);
|
|
36
37
|
if (addon.protocolVersion() !== PROTOCOL_VERSION) {
|
|
37
38
|
throw mismatch(addon.version(), 'the addon', addon.protocolVersion());
|
|
38
39
|
}
|
|
40
|
+
readPdfsWith(addon, env, options.binaryPath);
|
|
39
41
|
return new Fastbrowse(new InProcess(addon, options.env ?? {}), addon.version(), browserParams(options));
|
|
40
42
|
}
|
|
41
|
-
const env = { ...process.env, ...options.env };
|
|
42
43
|
const binary = resolveBinary(options.binaryPath, env);
|
|
43
44
|
const server = new Server(binary, env, options.stderr ?? 'inherit');
|
|
44
45
|
try {
|
package/dist/index.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
export { AbortError, FastbrowseError, ProcessExitedError, RpcError } from './errors.ts';
|
|
2
2
|
export { type CloseOptions, Fastbrowse, type StartOptions } from './fastbrowse.ts';
|
|
3
3
|
export { type JsonSchema, type OutputIssue, type OutputOf, type OutputSchema, OutputValidationError, type StandardOutputSchema, type TypedRunResult, } from './output.ts';
|
|
4
|
-
export type { Artifact, BrowserEvent, BudgetStop, Citation, CostBreakdown, CostLine, ErrorCode, Evidence, RunResult, SecretRef, Status, StepChoice, StepEvent, StepFact, StepResult, } from './protocol.ts';
|
|
4
|
+
export type { Artifact, BrowserEvent, BrowserWarningEvent, BudgetStop, CancellationReceipt, Citation, CostBreakdown, CostLine, ErrorCode, Evidence, RunResult, SecretRef, Status, StepChoice, StepEvent, StepFact, StepResult, } from './protocol.ts';
|
|
5
5
|
export type { Attachment, BrowserOptions, RunOptions, Secrets } from './run.ts';
|
package/dist/protocol.d.ts
CHANGED
|
@@ -1,26 +1,36 @@
|
|
|
1
|
-
export type ArtifactKind = 'download';
|
|
2
|
-
export type CostBasis = 'metered' | 'estimated' | 'bounded' | 'unknown';
|
|
3
|
-
export type CostComponent = 'jev' | 'llm' | 'browser' | 'proxy';
|
|
4
|
-
export type LLMPurpose = 'plan' | 'read' | 'field_text' | 'recover' | 'verify' | 'compose' | 'shortcut';
|
|
1
|
+
export type ArtifactKind = 'download' | 'screenshot' | 'capture';
|
|
5
2
|
/**
|
|
6
|
-
*
|
|
7
|
-
* reader's, because the reader asked for the rest of the list.
|
|
3
|
+
* How a run reached the browser it drove.
|
|
8
4
|
*/
|
|
9
|
-
export type
|
|
5
|
+
export type BrowserVia = 'cloud' | 'launched' | 'attached' | 'extension';
|
|
6
|
+
export type BrowserWarningOperation = 'screencast_start' | 'screencast_stop' | 'screencast_frame_ack' | 'paint_keeper_attach' | 'popup_setup_close' | 'popup_setup_release' | 'frame_callback_shutdown' | 'live_frame_delivery' | 'download_capture';
|
|
7
|
+
export type BrowserWarningFailure = 'browser_error' | 'context_lost' | 'browser_unavailable' | 'screenshots_unavailable' | 'navigation_timeout' | 'site_unreachable' | 'browser_unresponsive' | 'page_unresponsive' | 'origin_not_allowed' | 'script_error' | 'timeout' | 'callback_exception' | 'payload_decode' | 'capture_failed' | 'cancelled';
|
|
8
|
+
export type Operation = 'click' | 'hover' | 'drag' | 'fill' | 'press' | 'blur' | 'select' | 'enter' | 'escape' | 'scroll' | 'scroll_up' | 'back' | 'switch_tab' | 'upload' | 'dialog' | 'wait' | 'read' | 'done' | 'navigate' | 'search';
|
|
9
|
+
/**
|
|
10
|
+
* Who chose a step: Jev, a rule in code, or a saved recipe action confirmed by Jev.
|
|
11
|
+
*/
|
|
12
|
+
export type Decider = 'jev' | 'code' | 'recipe';
|
|
13
|
+
export type StepOutcome = 'executed' | 'covered' | 'stale' | 'failed';
|
|
14
|
+
/**
|
|
15
|
+
* A closed reason for a failed browser step; ``note`` remains diagnostic text.
|
|
16
|
+
*/
|
|
17
|
+
export type StepFailure = 'missing_target' | 'target_gone' | 'unauthorized_origin' | 'navigation_failed' | 'dialog_interrupted' | 'browser_error';
|
|
18
|
+
export type FactReader = 'jev_choice' | 'llm_image';
|
|
19
|
+
export type CostComponent = 'jev' | 'llm' | 'browser' | 'proxy' | 'search';
|
|
20
|
+
export type CostBasis = 'metered' | 'estimated' | 'bounded' | 'unsettled' | 'unknown';
|
|
21
|
+
export type LLMPurpose = 'start' | 'compose' | 'image_read' | 'fill' | 'pages' | 'dates' | 'known_pages' | 'recovery_pages' | 'search' | 'unobtainable' | 'groups' | 'action';
|
|
22
|
+
export type JevPurpose = 'action' | 'authorization' | 'relevance' | 'read' | 'verify' | 'locate';
|
|
10
23
|
/**
|
|
11
24
|
* Every code an error reply can carry: the JSON-RPC standard ones, then this protocol's own.
|
|
12
25
|
*/
|
|
13
26
|
export type ErrorCode = -32700 | -32600 | -32601 | -32602 | -32603 | -32001 | -32002 | -32003 | -32004;
|
|
14
27
|
export type RequestId = number | string;
|
|
15
|
-
export type FactReader = 'jev_choice' | 'llm';
|
|
16
28
|
export type JsonValue = unknown;
|
|
17
29
|
/**
|
|
18
30
|
* What the server sends without being asked.
|
|
19
31
|
*/
|
|
20
32
|
export type ServerMethod = 'run/event' | 'run/frame' | 'run/until' | 'secrets/resolve';
|
|
21
|
-
export type
|
|
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';
|
|
33
|
+
export type Status = 'complete' | 'unverified' | 'needs_confirmation' | 'needs_login' | 'blocked' | 'needs_input' | 'stuck' | 'budget_exceeded' | 'observation_limit' | 'unavailable' | 'cancelled' | 'error';
|
|
24
34
|
/**
|
|
25
35
|
* What a sign-in or bot wall asks of the person who has to get the run past it.
|
|
26
36
|
*/
|
|
@@ -57,20 +67,100 @@ export interface BrowserEvent {
|
|
|
57
67
|
*/
|
|
58
68
|
browser_id: string | null;
|
|
59
69
|
}
|
|
70
|
+
/**
|
|
71
|
+
* The browser a run drove.
|
|
72
|
+
*/
|
|
73
|
+
export interface BrowserUsed {
|
|
74
|
+
via: BrowserVia;
|
|
75
|
+
/**
|
|
76
|
+
* The profile it ran in, when one was named: a local profile directory, a cloud profile, or the label of a
|
|
77
|
+
* browser connected through the extension.
|
|
78
|
+
*/
|
|
79
|
+
profile: string | null;
|
|
80
|
+
/**
|
|
81
|
+
* The browser's product and version, when known, such as `Chrome 150.0.7400.2`.
|
|
82
|
+
*/
|
|
83
|
+
browser: string | null;
|
|
84
|
+
}
|
|
85
|
+
/**
|
|
86
|
+
* A browser warning with only a closed operation and failure kind; it contains no page or transport text.
|
|
87
|
+
*/
|
|
88
|
+
export interface BrowserWarningEvent {
|
|
89
|
+
type: 'browser_warning';
|
|
90
|
+
operation: BrowserWarningOperation;
|
|
91
|
+
failure: BrowserWarningFailure;
|
|
92
|
+
}
|
|
60
93
|
export interface BudgetStop {
|
|
61
94
|
resource: 'steps' | 'dollars' | 'seconds' | 'jev_calls' | 'llm_calls';
|
|
62
95
|
limit: number;
|
|
63
96
|
}
|
|
64
|
-
|
|
97
|
+
/**
|
|
98
|
+
* What a cancelled run did before it stopped: the `data` of its `cancelled` error.
|
|
99
|
+
*
|
|
100
|
+
* A cancelled run proved nothing, so this has no status and no answer. It holds what the caller is owed
|
|
101
|
+
* whatever the run became: the steps it reported, every charge known when it stopped, an unpriced one as an
|
|
102
|
+
* `unknown` line, and the videos finished before its browser closed. A step cut off before its event was sent
|
|
103
|
+
* was never reported, so it is not among the steps.
|
|
104
|
+
*/
|
|
105
|
+
export interface CancellationReceipt {
|
|
106
|
+
steps: StepResult[];
|
|
107
|
+
cost: CostBreakdown;
|
|
108
|
+
recordings: string[];
|
|
109
|
+
browser: BrowserUsed | null;
|
|
110
|
+
}
|
|
111
|
+
export interface StepResult {
|
|
112
|
+
index: number;
|
|
113
|
+
operation: Operation;
|
|
114
|
+
decided_by: Decider;
|
|
115
|
+
outcome: StepOutcome;
|
|
116
|
+
failure: StepFailure | null;
|
|
117
|
+
url: string;
|
|
65
118
|
/**
|
|
66
|
-
*
|
|
119
|
+
* Human-readable label of the chosen element; never contains a secret value.
|
|
67
120
|
*/
|
|
68
|
-
|
|
121
|
+
target: string | null;
|
|
122
|
+
confidence: number | null;
|
|
123
|
+
note: string | null;
|
|
124
|
+
/**
|
|
125
|
+
* Facts added to the notes by this step, with resolved secrets redacted.
|
|
126
|
+
*/
|
|
127
|
+
facts: StepFact[];
|
|
128
|
+
/**
|
|
129
|
+
* Whether the page's fingerprint changed; None for steps that do not act (read).
|
|
130
|
+
*/
|
|
131
|
+
page_changed: boolean | null;
|
|
132
|
+
duration_ms: number;
|
|
133
|
+
/**
|
|
134
|
+
* The controls Jev was offered for this step's decision, when `Config.step_choices` asked for them.
|
|
135
|
+
*/
|
|
136
|
+
choices?: StepChoice[];
|
|
137
|
+
}
|
|
138
|
+
export interface StepFact {
|
|
69
139
|
text: string;
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
140
|
+
/**
|
|
141
|
+
* None for a count, total or winner derived from other facts rather than read from the page.
|
|
142
|
+
*/
|
|
143
|
+
quote: string | null;
|
|
144
|
+
url: string | null;
|
|
145
|
+
reader: FactReader;
|
|
146
|
+
deep_link: string | null;
|
|
147
|
+
}
|
|
148
|
+
export interface StepChoice {
|
|
149
|
+
id: string;
|
|
150
|
+
role: string;
|
|
151
|
+
/**
|
|
152
|
+
* The label as Jev read it, with resolved secrets masked.
|
|
153
|
+
*/
|
|
154
|
+
label: string;
|
|
155
|
+
/**
|
|
156
|
+
* The card or row that tells this control from its twins, as Jev read it, with resolved secrets masked.
|
|
157
|
+
*/
|
|
158
|
+
context: string | null;
|
|
159
|
+
operations: Operation[];
|
|
160
|
+
/**
|
|
161
|
+
* Whether Jev chose this control: the target, and for a drag the destination too.
|
|
162
|
+
*/
|
|
163
|
+
chosen: boolean;
|
|
74
164
|
}
|
|
75
165
|
export interface CostBreakdown {
|
|
76
166
|
lines: CostLine[];
|
|
@@ -80,16 +170,32 @@ export interface CostLine {
|
|
|
80
170
|
basis: CostBasis;
|
|
81
171
|
dollars: number | null;
|
|
82
172
|
purpose: LLMPurpose | null;
|
|
173
|
+
decision_purpose?: JevPurpose | null;
|
|
83
174
|
input_tokens: number;
|
|
84
175
|
output_tokens: number;
|
|
85
176
|
/**
|
|
86
|
-
* Wall time of the call, retries included
|
|
177
|
+
* Wall time of the call, retries included, or the time a metered browser was held. None when unknown.
|
|
87
178
|
*/
|
|
88
179
|
seconds: number | null;
|
|
180
|
+
/**
|
|
181
|
+
* Physical provider requests represented by this line; absent on historical receipts.
|
|
182
|
+
*/
|
|
183
|
+
physical_requests?: number | null;
|
|
184
|
+
}
|
|
185
|
+
export interface Citation {
|
|
186
|
+
/**
|
|
187
|
+
* The number used by this fact's links in the answer, stable within a run.
|
|
188
|
+
*/
|
|
189
|
+
id: number;
|
|
190
|
+
text: string;
|
|
191
|
+
url: string;
|
|
192
|
+
quote: string;
|
|
193
|
+
deep_link: string;
|
|
89
194
|
}
|
|
90
195
|
export interface Error {
|
|
91
196
|
code: ErrorCode;
|
|
92
197
|
message: string;
|
|
198
|
+
data?: CancellationReceipt | null;
|
|
93
199
|
}
|
|
94
200
|
export interface ErrorResponse {
|
|
95
201
|
jsonrpc: '2.0';
|
|
@@ -118,12 +224,26 @@ export interface Evidence {
|
|
|
118
224
|
* The headings the quote sits under on the page: which record a bare "£10.69" is the price of.
|
|
119
225
|
*/
|
|
120
226
|
heading_path: string[];
|
|
227
|
+
/**
|
|
228
|
+
* The `uri` of the `capture` artifact holding the page text `start` and `end` index into, if one was kept.
|
|
229
|
+
*/
|
|
230
|
+
capture_artifact?: string | null;
|
|
231
|
+
/**
|
|
232
|
+
* The links inside the quote and where each leads, which its text alone does not say.
|
|
233
|
+
*/
|
|
234
|
+
links?: Link[];
|
|
121
235
|
}
|
|
122
236
|
export interface SourceControl {
|
|
123
237
|
role: string;
|
|
124
238
|
label: string;
|
|
125
239
|
context: string | null;
|
|
126
240
|
}
|
|
241
|
+
export interface Link {
|
|
242
|
+
text: string;
|
|
243
|
+
start: number;
|
|
244
|
+
end: number;
|
|
245
|
+
href: string;
|
|
246
|
+
}
|
|
127
247
|
/**
|
|
128
248
|
* The client's side of the handshake.
|
|
129
249
|
*
|
|
@@ -226,7 +346,7 @@ export interface RunCancelParams {
|
|
|
226
346
|
*/
|
|
227
347
|
export interface RunEvent {
|
|
228
348
|
run_id: string;
|
|
229
|
-
event: StepEvent | BrowserEvent;
|
|
349
|
+
event: StepEvent | BrowserEvent | BrowserWarningEvent;
|
|
230
350
|
}
|
|
231
351
|
export interface StepEvent {
|
|
232
352
|
type: 'step';
|
|
@@ -237,60 +357,6 @@ export interface StepEvent {
|
|
|
237
357
|
*/
|
|
238
358
|
frame: string | null;
|
|
239
359
|
}
|
|
240
|
-
export interface StepResult {
|
|
241
|
-
index: number;
|
|
242
|
-
operation: Operation;
|
|
243
|
-
decided_by: Decider;
|
|
244
|
-
outcome: StepOutcome;
|
|
245
|
-
url: string;
|
|
246
|
-
/**
|
|
247
|
-
* Human-readable label of the chosen element; never contains a secret value.
|
|
248
|
-
*/
|
|
249
|
-
target: string | null;
|
|
250
|
-
confidence: number | null;
|
|
251
|
-
note: string | null;
|
|
252
|
-
/**
|
|
253
|
-
* Facts added to the notes by this step, with resolved secrets redacted.
|
|
254
|
-
*/
|
|
255
|
-
facts: StepFact[];
|
|
256
|
-
/**
|
|
257
|
-
* Whether the page's fingerprint changed; None for steps that do not act (read, escalate).
|
|
258
|
-
*/
|
|
259
|
-
page_changed: boolean | null;
|
|
260
|
-
duration_ms: number;
|
|
261
|
-
/**
|
|
262
|
-
* The controls Jev was offered for this step's decision, when `Config.step_choices` asked for them.
|
|
263
|
-
*/
|
|
264
|
-
choices?: StepChoice[];
|
|
265
|
-
}
|
|
266
|
-
export interface StepFact {
|
|
267
|
-
text: string;
|
|
268
|
-
requirement_id: string | null;
|
|
269
|
-
/**
|
|
270
|
-
* None for a count, total or winner derived from other facts rather than read from the page.
|
|
271
|
-
*/
|
|
272
|
-
quote: string | null;
|
|
273
|
-
url: string | null;
|
|
274
|
-
reader: FactReader;
|
|
275
|
-
deep_link: string | null;
|
|
276
|
-
}
|
|
277
|
-
export interface StepChoice {
|
|
278
|
-
id: string;
|
|
279
|
-
role: string;
|
|
280
|
-
/**
|
|
281
|
-
* The label as Jev read it, with resolved secrets masked.
|
|
282
|
-
*/
|
|
283
|
-
label: string;
|
|
284
|
-
/**
|
|
285
|
-
* The card or row that tells this control from its twins, as Jev read it, with resolved secrets masked.
|
|
286
|
-
*/
|
|
287
|
-
context: string | null;
|
|
288
|
-
operations: Operation[];
|
|
289
|
-
/**
|
|
290
|
-
* Whether Jev chose this control: the target, and for a drag the destination too.
|
|
291
|
-
*/
|
|
292
|
-
chosen: boolean;
|
|
293
|
-
}
|
|
294
360
|
/**
|
|
295
361
|
* The params of `run/frame`: the active tab as it looked a moment ago. Sent only to a run that set `frames`.
|
|
296
362
|
*/
|
|
@@ -299,13 +365,16 @@ export interface RunFrame {
|
|
|
299
365
|
frame: string;
|
|
300
366
|
}
|
|
301
367
|
/**
|
|
302
|
-
* One run
|
|
368
|
+
* One run: the run's arguments, and what the server needs to talk to the client about it.
|
|
303
369
|
*
|
|
304
370
|
* The reply is the `RunResult`. No API key is among the fields: model and browser keys come from the
|
|
305
371
|
* environment the server inherited.
|
|
306
372
|
*/
|
|
307
373
|
export interface RunParams {
|
|
308
374
|
run_id: string;
|
|
375
|
+
secrets?: SecretRef[];
|
|
376
|
+
frames?: boolean;
|
|
377
|
+
until?: boolean;
|
|
309
378
|
task: string;
|
|
310
379
|
start?: string | null;
|
|
311
380
|
context?: string | null;
|
|
@@ -318,13 +387,13 @@ export interface RunParams {
|
|
|
318
387
|
output_schema?: {
|
|
319
388
|
[k: string]: unknown;
|
|
320
389
|
} | null;
|
|
321
|
-
secrets?: SecretRef[];
|
|
322
|
-
frames?: boolean;
|
|
323
|
-
until?: boolean;
|
|
324
390
|
downloads?: string | null;
|
|
325
391
|
record?: string | null;
|
|
326
|
-
|
|
392
|
+
recipe?: string | null;
|
|
393
|
+
save_recipe?: string | null;
|
|
394
|
+
cursor?: boolean | null;
|
|
327
395
|
local?: boolean;
|
|
396
|
+
launch?: boolean;
|
|
328
397
|
chrome?: LocalChrome | null;
|
|
329
398
|
cloud_profile?: string | null;
|
|
330
399
|
cdp_url?: string | null;
|
|
@@ -334,7 +403,14 @@ export interface RunParams {
|
|
|
334
403
|
foreground?: boolean;
|
|
335
404
|
proxy_country?: string | null;
|
|
336
405
|
viewport?: [number, number] | null;
|
|
337
|
-
|
|
406
|
+
cloud_extensions?: string[];
|
|
407
|
+
cloud_timeout_minutes?: number | null;
|
|
408
|
+
allowed_origins?: string[] | null;
|
|
409
|
+
fetch?: boolean;
|
|
410
|
+
browser?: boolean;
|
|
411
|
+
extension?: boolean;
|
|
412
|
+
extension_browser?: string | null;
|
|
413
|
+
desktop?: string | null;
|
|
338
414
|
}
|
|
339
415
|
export interface SecretRef {
|
|
340
416
|
name: string;
|
|
@@ -354,6 +430,10 @@ export interface RunResult {
|
|
|
354
430
|
artifacts: Artifact[];
|
|
355
431
|
citations: Citation[];
|
|
356
432
|
error: string | null;
|
|
433
|
+
/**
|
|
434
|
+
* The error's provider or browser variant path, never message text; present for failures, absent otherwise.
|
|
435
|
+
*/
|
|
436
|
+
failure_kind: string | null;
|
|
357
437
|
/**
|
|
358
438
|
* Where the browser was last observed; what a caller checks when the task was to arrive somewhere.
|
|
359
439
|
*/
|
|
@@ -366,6 +446,10 @@ export interface RunResult {
|
|
|
366
446
|
* The sign-in or bot wall a `needs_login` or `blocked` run stopped at, when the page showed one.
|
|
367
447
|
*/
|
|
368
448
|
wall: Wall | null;
|
|
449
|
+
/**
|
|
450
|
+
* The browser the run drove, and how it reached it; none when it read every page over HTTP.
|
|
451
|
+
*/
|
|
452
|
+
browser: BrowserUsed | null;
|
|
369
453
|
}
|
|
370
454
|
/**
|
|
371
455
|
* The wall a `needs_login` or `blocked` run stopped at, typed so a caller can route it without parsing `error`.
|
|
@@ -430,7 +514,7 @@ export declare const Method: {
|
|
|
430
514
|
readonly RUN_CANCEL: 'run/cancel';
|
|
431
515
|
readonly SHUTDOWN: 'shutdown';
|
|
432
516
|
};
|
|
433
|
-
export declare const PROTOCOL_VERSION =
|
|
517
|
+
export declare const PROTOCOL_VERSION = 3;
|
|
434
518
|
export declare const ServerMethod: {
|
|
435
519
|
readonly RUN_EVENT: 'run/event';
|
|
436
520
|
readonly RUN_FRAME: 'run/frame';
|
package/dist/protocol.js
CHANGED
package/dist/rpc.d.ts
CHANGED
|
@@ -8,7 +8,6 @@ export declare class Connection {
|
|
|
8
8
|
constructor(input: Readable, output: Writable);
|
|
9
9
|
/** Call a method and wait for its reply. Rejects with `RpcError` when the server answers with an error. */
|
|
10
10
|
request(method: string, params?: object): Promise<unknown>;
|
|
11
|
-
notify(method: string, params?: Params): void;
|
|
12
11
|
/** Serve a method the server calls on this side. */
|
|
13
12
|
onRequest(method: string, handler: RequestHandler): void;
|
|
14
13
|
onNotification(method: string, handler: NotificationHandler): void;
|
package/dist/rpc.js
CHANGED
|
@@ -34,10 +34,6 @@ export class Connection {
|
|
|
34
34
|
this.#send({ id, method, params });
|
|
35
35
|
});
|
|
36
36
|
}
|
|
37
|
-
notify(method, params = {}) {
|
|
38
|
-
if (!this.#ended)
|
|
39
|
-
this.#send({ method, params });
|
|
40
|
-
}
|
|
41
37
|
/** Serve a method the server calls on this side. */
|
|
42
38
|
onRequest(method, handler) {
|
|
43
39
|
this.#requests.set(method, handler);
|
|
@@ -77,8 +73,8 @@ export class Connection {
|
|
|
77
73
|
return;
|
|
78
74
|
this.#pending.delete(message.id);
|
|
79
75
|
if (message.error) {
|
|
80
|
-
const { code, message: text } = message.error;
|
|
81
|
-
pending.reject(new RpcError(code, text));
|
|
76
|
+
const { code, message: text, data } = message.error;
|
|
77
|
+
pending.reject(new RpcError(code, text, data ?? undefined));
|
|
82
78
|
}
|
|
83
79
|
else {
|
|
84
80
|
pending.resolve(message.result);
|
package/dist/run.d.ts
CHANGED
|
@@ -1,15 +1,17 @@
|
|
|
1
1
|
import { type OutputSchema } from './output.ts';
|
|
2
|
-
import type { Authorization, BrowserEvent, Limits, LocalChrome, RunParams, SecretRef, StepEvent } from './protocol.ts';
|
|
2
|
+
import type { Authorization, BrowserEvent, BrowserWarningEvent, Limits, LocalChrome, RunParams, SecretRef, StepEvent } from './protocol.ts';
|
|
3
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
|
|
4
|
+
/** A wire model with its field names in camelCase, so its fields follow the wire model without a second list. */
|
|
5
5
|
export type CamelKeys<Model> = {
|
|
6
6
|
[Name in keyof Model as Camel<Name & string>]: Model[Name];
|
|
7
7
|
};
|
|
8
8
|
/** Which browser a run drives. Given to `Fastbrowse.start`, these are the defaults of every run it makes. */
|
|
9
9
|
export interface BrowserOptions {
|
|
10
|
-
/**
|
|
10
|
+
/** A browser on this machine instead of a Browser Use Cloud browser: your own Chrome through the fastbrowse extension, unless `launch` asks for a separate one. */
|
|
11
11
|
local?: boolean;
|
|
12
|
-
/**
|
|
12
|
+
/** Start a separate local Chrome instead of driving your own through the extension. Implies `local`. */
|
|
13
|
+
launch?: boolean;
|
|
14
|
+
/** Which local Chrome, and how. A headed window or a kept profile implies `launch`. */
|
|
13
15
|
chrome?: CamelKeys<LocalChrome>;
|
|
14
16
|
cloudProfile?: string;
|
|
15
17
|
/** The DevTools WebSocket URL of a browser that is already running. The run neither starts nor stops it. */
|
|
@@ -25,7 +27,10 @@ export interface BrowserOptions {
|
|
|
25
27
|
/** The two-letter country a cloud browser browses from. */
|
|
26
28
|
proxyCountry?: string;
|
|
27
29
|
viewport?: [width: number, height: number];
|
|
28
|
-
|
|
30
|
+
/** Up to three IDs of ready extensions on the Browser Use Cloud account, loaded into a cloud browser. */
|
|
31
|
+
cloudExtensions?: string[];
|
|
32
|
+
/** How long a cloud browser may live, in minutes: 15 when none is given, and the service allows up to 240. */
|
|
33
|
+
cloudTimeoutMinutes?: number;
|
|
29
34
|
}
|
|
30
35
|
export interface Attachment {
|
|
31
36
|
name: string;
|
|
@@ -70,16 +75,38 @@ export interface RunOptions extends PerRun<BrowserOptions> {
|
|
|
70
75
|
downloads?: string;
|
|
71
76
|
/** Where to write a video of the run. The server needs ffmpeg for it. */
|
|
72
77
|
record?: string;
|
|
73
|
-
/**
|
|
78
|
+
/** Replay a recipe file and heal unmatched steps. */
|
|
79
|
+
recipe?: string;
|
|
80
|
+
/** Save completed steps to a recipe file. */
|
|
81
|
+
saveRecipe?: string;
|
|
82
|
+
/** The agent's cursor over visible local Chrome on Linux X11 with Cua Driver: unset draws it wherever it can be placed, true also brings the window to the front for it, false turns it off. */
|
|
74
83
|
cursor?: boolean;
|
|
84
|
+
/**
|
|
85
|
+
* The only `http(s)://host[:port]` origins whose documents the run may open, read and control, each exact. A
|
|
86
|
+
* navigation, redirect, frame or popup elsewhere is refused before it is sent. It scopes documents, not the
|
|
87
|
+
* network, and a scoped run sends no frames and cannot `record`. Without it the run is unscoped.
|
|
88
|
+
*/
|
|
89
|
+
allowedOrigins?: string[];
|
|
90
|
+
/** Read every page over HTTP and start no browser, for a task that only reads. */
|
|
91
|
+
fetch?: boolean;
|
|
92
|
+
/** Start a browser from the first step, rather than reading over HTTP until the task needs one. */
|
|
93
|
+
browser?: boolean;
|
|
94
|
+
/**
|
|
95
|
+
* Run in the user's own Chrome, signed in as they are, through the fastbrowse extension
|
|
96
|
+
* (`fastbrowse extension install`). With no browser connected the run ends `unavailable` before any spend.
|
|
97
|
+
*/
|
|
98
|
+
extension?: boolean;
|
|
99
|
+
/** Which browser the extension is connected in, by the label its popup shows. Implies `extension`. */
|
|
100
|
+
extensionBrowser?: string;
|
|
75
101
|
secrets?: Secrets;
|
|
76
102
|
/** Called with the address the run ended on. Anything but true keeps the run from `complete`. */
|
|
77
103
|
until?: (url: string) => MaybePromise<boolean>;
|
|
78
104
|
/**
|
|
79
|
-
* Called with the browser event
|
|
80
|
-
* callback here, one that throws or rejects ends the run with
|
|
105
|
+
* Called with the browser event, step events, and typed browser warnings. Warning codes contain no page
|
|
106
|
+
* content or transport error text. Like any callback here, one that throws or rejects ends the run with
|
|
107
|
+
* status `error`.
|
|
81
108
|
*/
|
|
82
|
-
onEvent?: (event: StepEvent | BrowserEvent) => void;
|
|
109
|
+
onEvent?: (event: StepEvent | BrowserEvent | BrowserWarningEvent) => void;
|
|
83
110
|
/** Called with JPEG frames of the active tab while the run goes on. Without it the page is never filmed. */
|
|
84
111
|
onFrame?: (frame: Uint8Array) => void;
|
|
85
112
|
/**
|
package/dist/run.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
// What a caller passes to `run`, and the `run` request it becomes. Options are camelCase, and the wire keeps the
|
|
2
|
-
//
|
|
2
|
+
// protocol's snake_case names.
|
|
3
3
|
import { wireSchema } from './output.js';
|
|
4
4
|
/** The fields that were given. A default must survive a per-run option that is there but undefined. */
|
|
5
5
|
function given(fields) {
|
|
@@ -19,6 +19,7 @@ function snakeKeys(fields) {
|
|
|
19
19
|
function browserFields(options) {
|
|
20
20
|
return given({
|
|
21
21
|
local: options.local,
|
|
22
|
+
launch: options.launch,
|
|
22
23
|
chrome: options.chrome && snakeKeys(options.chrome),
|
|
23
24
|
cloud_profile: options.cloudProfile,
|
|
24
25
|
cdp_url: options.cdpUrl,
|
|
@@ -28,7 +29,8 @@ function browserFields(options) {
|
|
|
28
29
|
foreground: options.foreground,
|
|
29
30
|
proxy_country: options.proxyCountry,
|
|
30
31
|
viewport: options.viewport,
|
|
31
|
-
|
|
32
|
+
cloud_extensions: options.cloudExtensions,
|
|
33
|
+
cloud_timeout_minutes: options.cloudTimeoutMinutes,
|
|
32
34
|
});
|
|
33
35
|
}
|
|
34
36
|
/** The browser every run of an instance uses, as the fields of a `run` request. */
|
|
@@ -53,7 +55,14 @@ export function runParams(runId, task, defaults, options) {
|
|
|
53
55
|
output_schema: options.output && wireSchema(options.output),
|
|
54
56
|
downloads: options.downloads,
|
|
55
57
|
record: options.record,
|
|
58
|
+
recipe: options.recipe,
|
|
59
|
+
save_recipe: options.saveRecipe,
|
|
56
60
|
cursor: options.cursor,
|
|
61
|
+
allowed_origins: options.allowedOrigins,
|
|
62
|
+
fetch: options.fetch,
|
|
63
|
+
browser: options.browser,
|
|
64
|
+
extension: options.extension,
|
|
65
|
+
extension_browser: options.extensionBrowser,
|
|
57
66
|
secrets: options.secrets?.refs,
|
|
58
67
|
// The wire carries whether a callback is held, and the callback stays here.
|
|
59
68
|
frames: options.onFrame && true,
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "fastbrowse",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.11.1",
|
|
4
4
|
"description": "Browser automation with cited answers, structured output and code-controlled credentials and authorization.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -27,10 +27,10 @@
|
|
|
27
27
|
"test": "npm run build && node --test \"test/*.test.ts\""
|
|
28
28
|
},
|
|
29
29
|
"optionalDependencies": {
|
|
30
|
-
"@fastbrowse/darwin-arm64": "0.
|
|
31
|
-
"@fastbrowse/darwin-x64": "0.
|
|
32
|
-
"@fastbrowse/linux-arm64": "0.
|
|
33
|
-
"@fastbrowse/linux-x64": "0.
|
|
34
|
-
"@fastbrowse/win32-x64": "0.
|
|
30
|
+
"@fastbrowse/darwin-arm64": "0.11.1",
|
|
31
|
+
"@fastbrowse/darwin-x64": "0.11.1",
|
|
32
|
+
"@fastbrowse/linux-arm64": "0.11.1",
|
|
33
|
+
"@fastbrowse/linux-x64": "0.11.1",
|
|
34
|
+
"@fastbrowse/win32-x64": "0.11.1"
|
|
35
35
|
}
|
|
36
36
|
}
|