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 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
- `TYPESAFE_API_KEY` is the recommended Jev route. `OPENROUTER_API_KEY` serves the LLM and, when it is the
16
- only Jev key, Jev text; it is not the recommended Jev route and never receives Jev image input. Without it,
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 the Chrome on your machine. Without it a run starts a
24
- Browser Use Cloud browser, which needs `BROWSER_USE_API_KEY`.
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 `cloudAllowResizing`. `Fastbrowse.start`
76
- takes the browser choices as defaults for every run, and a run passes `null` for one to go without that default.
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`. A run that finished before the cancellation reached it resolves
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`. A run that finished before the cancellation reached it resolves
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();
@@ -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
- /** The result of a run that a throwing callback ended, in the shape the server gives one. */
101
- function endedBy(failure) {
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
- constructor(reason: unknown);
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
- constructor(code: number, message: string);
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
- constructor(reason) {
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
- constructor(code, message) {
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
  }
@@ -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` and `stderr` mean nothing.
21
+ * `binaryPath` selects its PDF helper process; `stderr` has no effect.
22
22
  */
23
23
  inProcess?: boolean;
24
24
  /**
@@ -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, { ...process.env, ...options.env });
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';
@@ -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
- * 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.
3
+ * How a run reached the browser it drove.
8
4
  */
9
- export type Decider = 'jev' | 'llm';
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 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';
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
- export interface Citation {
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
- * The number used by this fact's links in the answer, stable within a run.
119
+ * Human-readable label of the chosen element; never contains a secret value.
67
120
  */
68
- id: number;
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
- requirement_id: string | null;
71
- url: string;
72
- quote: string;
73
- deep_link: string;
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. None for a line that is not one call, such as browser time.
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. Apart from `run_id`, each field is the `run_task` argument or the CLI flag of the same name.
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
- cursor?: boolean;
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
- cloud_allow_resizing?: boolean;
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 = 1;
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
@@ -17,7 +17,7 @@ export const Method = {
17
17
  RUN_CANCEL: 'run/cancel',
18
18
  SHUTDOWN: 'shutdown',
19
19
  };
20
- export const PROTOCOL_VERSION = 1;
20
+ export const PROTOCOL_VERSION = 3;
21
21
  export const ServerMethod = {
22
22
  RUN_EVENT: 'run/event',
23
23
  RUN_FRAME: 'run/frame',
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 Python model without a second list. */
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
- /** Local Chrome instead of a Browser Use Cloud browser. */
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
- /** Which local Chrome, and how. A headed window or a kept profile implies `local`. */
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
- cloudAllowResizing?: boolean;
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
- /** Draw visual cursor feedback for visible local Chrome on Linux X11 with Cua Driver. */
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 and then each step event, in the order the run produced them. Like any
80
- * callback here, one that throws or rejects ends the run with status `error`.
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
- // Python models' snake_case names.
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
- cloud_allow_resizing: options.cloudAllowResizing,
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.9.1",
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.9.1",
31
- "@fastbrowse/darwin-x64": "0.9.1",
32
- "@fastbrowse/linux-arm64": "0.9.1",
33
- "@fastbrowse/linux-x64": "0.9.1",
34
- "@fastbrowse/win32-x64": "0.9.1"
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
  }