fastbrowse 0.9.1 → 0.10.0

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,13 +8,11 @@ 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
@@ -52,17 +50,33 @@ stopped it in `result.wall`: `kind` is `password`, `one_time_code`, `sign_in` or
52
50
  a second `run` while one is active rejects with the busy error, so start more instances to run side by side.
53
51
  `close()` shuts the process down and waits for it, and the process also exits when yours does.
54
52
 
53
+ `Fastbrowse.start({ inProcess: true })` runs on the native addon in your Node process. PDF reading still uses a
54
+ helper binary, selected by `binaryPath`, then `FASTBROWSE_BINARY`, then the installed platform package. Keep the
55
+ addon and helper on matching fastbrowse versions.
56
+
55
57
  `run` rejects when no run took place or none finished: with `RpcError` when the server refuses the request before
56
58
  a browser opens (a bad option, a missing key, a busy server), with `AbortError` when `signal` stopped the run, and
57
59
  with `ProcessExitedError` when the process is gone. It also rejects with `OutputValidationError` when a run
58
60
  finished but its data fails the `output` schema. A run that fails after it starts, including one whose
59
61
  callback throws, resolves with status `error`.
60
62
 
63
+ Jev cost lines include `decision_purpose` when the agent named the decision: `action`, `authorization`,
64
+ `relevance`, `read`, `verify` or `locate`. LLM lines keep their existing `purpose`. An unscoped decision
65
+ client call omits the optional field, and older receipts remain readable.
66
+
67
+ An `AbortError` carries `receipt` once the server has closed the browser: the steps it reported, known cost
68
+ lines and finished recordings. A cancelled `RpcError` carries the same receipt. A cancellation before the run
69
+ starts has none. The receipt has no status or answer, and an unpriced charge remains `unknown`.
70
+
61
71
  ## Options
62
72
 
63
73
  The result is the `RunResult` the Python library returns. Its fields keep their Python names, such as
64
74
  `final_url`, since the types are generated from the protocol's schema; the options are camelCase.
65
75
 
76
+ A safe final screenshot is returned in `result.artifacts` with `kind: "screenshot"`, `mime_type: "image/png"`,
77
+ a SHA-256 digest and a base64 data URI in `uri`. A task can request the screenshot without enabling step frames.
78
+ If a resolved secret is visible, the image is withheld.
79
+
66
80
  `output` is `data` after a Zod (4.2 or newer) or ArkType schema's validation and transforms, or a Valibot schema
67
81
  wrapped by `@valibot/to-json-schema`, typed as the schema's output. Data the schema refuses rejects with
68
82
  `OutputValidationError`, which carries the result. A plain JSON Schema object is accepted too; `output` is then
@@ -70,11 +84,20 @@ wrapped by `@valibot/to-json-schema`, typed as the schema's output. Data the sch
70
84
  any other keyword by name, but a run fills only a flat object of required string, number, integer and boolean
71
85
  fields. With any other field it ends `unverified` with no data.
72
86
 
73
- `run` also takes `context`, `inputs`, `attachments` as bytes, `downloads`, `record`, `onFrame` (JPEG frames of the
87
+ `run` also takes `context`, `inputs`, `attachments` as bytes, `downloads`, `record`, `recipe`, `saveRecipe`, `onFrame` (JPEG frames of the
74
88
  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.
89
+ `attach`, `targetMatch`, `foreground`, `proxyCountry`, `viewport`, `cloudExtensions` and `cloudTimeoutMinutes`.
90
+ `Fastbrowse.start` takes the browser choices as defaults for every run, and a run passes `null` for one to go
91
+ without that default.
92
+
93
+ A run reads pages over HTTP until the task needs a browser. `fetch: true` never starts one, and `browser: true`
94
+ starts one from the first step; the server refuses the two together. `allowedOrigins` limits the documents a run
95
+ may open, read and control to those exact origins: navigations, redirects, frames and popups elsewhere are refused
96
+ before they are sent, so a sign-in that redirects through another origin needs it listed too. It scopes documents,
97
+ not the network, and a scoped run sends no frames and cannot `record`.
77
98
  `env` in `Fastbrowse.start` adds to the environment the process inherits.
99
+ 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;
100
+ `recipe` reuses saved values for matching live actions with the same task.
78
101
 
79
102
  ## Platforms
80
103
 
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,33 @@ 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
+ * Optional because an addon built before it still speaks protocol 2 and must still load with its original PDF
27
+ * handling. Make it required when the protocol version next changes, since the check in `Fastbrowse.start` then
28
+ * refuses every addon that lacks it before `readPdfsWith` is called.
29
+ */
30
+ setPdfHelper?(path: string): boolean;
23
31
  }
24
32
  /**
25
33
  * The addon to load: the caller's own path first, then the one the environment names, then the `fastbrowse.node`
26
34
  * beside the binary in the platform package.
27
35
  */
28
36
  export declare function loadAddon(addonPath: string | undefined, env: NodeJS.ProcessEnv): Addon;
37
+ /**
38
+ * Have `addon` read PDFs with the fastbrowse binary `env` resolves to, once its protocol is known to match. A PDF is
39
+ * read in a process the run can kill, and Node is no program the addon can run again for that: the binary beside it
40
+ * is. Without a binary, the current addon still runs and says of each PDF that its text went unread. An older
41
+ * addon without this method retains its original PDF handling.
42
+ */
43
+ export declare function readPdfsWith(addon: Addon, env: NodeJS.ProcessEnv, binaryPath?: string): void;
29
44
  /** Runs on the addon, one at a time as the fastbrowse process runs them, so the two modes answer alike. */
30
45
  export declare class InProcess {
31
46
  #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,24 @@ 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 current addon still runs and says of each PDF that its text went unread. An older
29
+ * addon without this method retains its original PDF handling.
30
+ */
31
+ export function readPdfsWith(addon, env, binaryPath) {
32
+ if (typeof addon.setPdfHelper !== 'function')
33
+ return;
34
+ let binary;
35
+ try {
36
+ binary = resolveBinary(binaryPath, env);
37
+ }
38
+ catch {
39
+ return;
40
+ }
41
+ addon.setPdfHelper(binary);
42
+ }
25
43
  /** The JSON a host function answers with. What a callback threw reaches the core as its message alone. */
26
44
  async function answered(call) {
27
45
  try {
@@ -74,7 +92,7 @@ export class InProcess {
74
92
  this.#active = undefined;
75
93
  }
76
94
  if (reply.error)
77
- throw new RpcError(reply.error.code, reply.error.message);
95
+ throw new RpcError(reply.error.code, reply.error.message, reply.error.data ?? undefined);
78
96
  return reply.result;
79
97
  };
80
98
  const stop = () => cancel.cancel();
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,25 @@ 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,
113
116
  final_url: null,
114
- recordings: [],
117
+ recordings: spent?.recordings ?? [],
115
118
  wall: null,
119
+ browser: spent?.browser ?? null,
116
120
  };
117
121
  }
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, 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,30 @@
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';
2
+ /**
3
+ * How a run reached the browser it drove.
4
+ */
5
+ export type BrowserVia = 'cloud' | 'launched' | 'attached' | 'extension';
6
+ export type Operation = 'click' | 'hover' | 'drag' | 'fill' | 'blur' | 'select' | 'enter' | 'escape' | 'scroll' | 'scroll_up' | 'back' | 'switch_tab' | 'upload' | 'dialog' | 'wait' | 'read' | 'done' | 'navigate';
5
7
  /**
6
- * The model whose choice a step carries out, even when code dispatches it: the next page of a list is the
7
- * reader's, because the reader asked for the rest of the list.
8
+ * Who chose a step: Jev, a rule in code, or a saved recipe action confirmed by Jev.
8
9
  */
9
- export type Decider = 'jev' | 'llm';
10
+ export type Decider = 'jev' | 'code' | 'recipe';
11
+ export type StepOutcome = 'executed' | 'covered' | 'stale' | 'failed';
12
+ export type FactReader = 'jev_choice' | 'llm_image';
13
+ export type CostComponent = 'jev' | 'llm' | 'browser' | 'proxy';
14
+ export type CostBasis = 'metered' | 'estimated' | 'bounded' | 'unsettled' | 'unknown';
15
+ export type LLMPurpose = 'start' | 'compose' | 'image_read' | 'fill' | 'pages' | 'dates';
16
+ export type JevPurpose = 'action' | 'authorization' | 'relevance' | 'read' | 'verify' | 'locate';
10
17
  /**
11
18
  * Every code an error reply can carry: the JSON-RPC standard ones, then this protocol's own.
12
19
  */
13
20
  export type ErrorCode = -32700 | -32600 | -32601 | -32602 | -32603 | -32001 | -32002 | -32003 | -32004;
14
21
  export type RequestId = number | string;
15
- export type FactReader = 'jev_choice' | 'llm';
16
22
  export type JsonValue = unknown;
17
23
  /**
18
24
  * What the server sends without being asked.
19
25
  */
20
26
  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';
27
+ export type Status = 'complete' | 'unverified' | 'needs_confirmation' | 'needs_login' | 'blocked' | 'needs_input' | 'stuck' | 'budget_exceeded' | 'observation_limit' | 'unavailable' | 'cancelled' | 'error';
24
28
  /**
25
29
  * What a sign-in or bot wall asks of the person who has to get the run past it.
26
30
  */
@@ -57,20 +61,91 @@ export interface BrowserEvent {
57
61
  */
58
62
  browser_id: string | null;
59
63
  }
64
+ /**
65
+ * The browser a run drove.
66
+ */
67
+ export interface BrowserUsed {
68
+ via: BrowserVia;
69
+ /**
70
+ * The profile it ran in, when one was named: a local profile directory, a cloud profile, or the label of a
71
+ * browser connected through the extension.
72
+ */
73
+ profile: string | null;
74
+ /**
75
+ * The browser's product and version, when known, such as `Chrome 150.0.7400.2`.
76
+ */
77
+ browser: string | null;
78
+ }
60
79
  export interface BudgetStop {
61
80
  resource: 'steps' | 'dollars' | 'seconds' | 'jev_calls' | 'llm_calls';
62
81
  limit: number;
63
82
  }
64
- export interface Citation {
83
+ /**
84
+ * What a cancelled run did before it stopped: the `data` of its `cancelled` error.
85
+ *
86
+ * A cancelled run proved nothing, so this has no status and no answer. It holds what the caller is owed
87
+ * whatever the run became: the steps it reported, every charge known when it stopped, an unpriced one as an
88
+ * `unknown` line, and the videos finished before its browser closed. A step cut off before its event was sent
89
+ * was never reported, so it is not among the steps.
90
+ */
91
+ export interface CancellationReceipt {
92
+ steps: StepResult[];
93
+ cost: CostBreakdown;
94
+ recordings: string[];
95
+ browser: BrowserUsed | null;
96
+ }
97
+ export interface StepResult {
98
+ index: number;
99
+ operation: Operation;
100
+ decided_by: Decider;
101
+ outcome: StepOutcome;
102
+ url: string;
65
103
  /**
66
- * The number used by this fact's links in the answer, stable within a run.
104
+ * Human-readable label of the chosen element; never contains a secret value.
67
105
  */
68
- id: number;
106
+ target: string | null;
107
+ confidence: number | null;
108
+ note: string | null;
109
+ /**
110
+ * Facts added to the notes by this step, with resolved secrets redacted.
111
+ */
112
+ facts: StepFact[];
113
+ /**
114
+ * Whether the page's fingerprint changed; None for steps that do not act (read).
115
+ */
116
+ page_changed: boolean | null;
117
+ duration_ms: number;
118
+ /**
119
+ * The controls Jev was offered for this step's decision, when `Config.step_choices` asked for them.
120
+ */
121
+ choices?: StepChoice[];
122
+ }
123
+ export interface StepFact {
69
124
  text: string;
70
- requirement_id: string | null;
71
- url: string;
72
- quote: string;
73
- deep_link: string;
125
+ /**
126
+ * None for a count, total or winner derived from other facts rather than read from the page.
127
+ */
128
+ quote: string | null;
129
+ url: string | null;
130
+ reader: FactReader;
131
+ deep_link: string | null;
132
+ }
133
+ export interface StepChoice {
134
+ id: string;
135
+ role: string;
136
+ /**
137
+ * The label as Jev read it, with resolved secrets masked.
138
+ */
139
+ label: string;
140
+ /**
141
+ * The card or row that tells this control from its twins, as Jev read it, with resolved secrets masked.
142
+ */
143
+ context: string | null;
144
+ operations: Operation[];
145
+ /**
146
+ * Whether Jev chose this control: the target, and for a drag the destination too.
147
+ */
148
+ chosen: boolean;
74
149
  }
75
150
  export interface CostBreakdown {
76
151
  lines: CostLine[];
@@ -80,16 +155,32 @@ export interface CostLine {
80
155
  basis: CostBasis;
81
156
  dollars: number | null;
82
157
  purpose: LLMPurpose | null;
158
+ decision_purpose?: JevPurpose | null;
83
159
  input_tokens: number;
84
160
  output_tokens: number;
85
161
  /**
86
- * Wall time of the call, retries included. None for a line that is not one call, such as browser time.
162
+ * Wall time of the call, retries included, or the time a metered browser was held. None when unknown.
87
163
  */
88
164
  seconds: number | null;
165
+ /**
166
+ * Physical provider requests represented by this line; absent on historical receipts.
167
+ */
168
+ physical_requests?: number | null;
169
+ }
170
+ export interface Citation {
171
+ /**
172
+ * The number used by this fact's links in the answer, stable within a run.
173
+ */
174
+ id: number;
175
+ text: string;
176
+ url: string;
177
+ quote: string;
178
+ deep_link: string;
89
179
  }
90
180
  export interface Error {
91
181
  code: ErrorCode;
92
182
  message: string;
183
+ data?: CancellationReceipt | null;
93
184
  }
94
185
  export interface ErrorResponse {
95
186
  jsonrpc: '2.0';
@@ -118,6 +209,10 @@ export interface Evidence {
118
209
  * The headings the quote sits under on the page: which record a bare "£10.69" is the price of.
119
210
  */
120
211
  heading_path: string[];
212
+ /**
213
+ * The `uri` of the `capture` artifact holding the page text `start` and `end` index into, if one was kept.
214
+ */
215
+ capture_artifact?: string | null;
121
216
  }
122
217
  export interface SourceControl {
123
218
  role: string;
@@ -237,60 +332,6 @@ export interface StepEvent {
237
332
  */
238
333
  frame: string | null;
239
334
  }
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
335
  /**
295
336
  * The params of `run/frame`: the active tab as it looked a moment ago. Sent only to a run that set `frames`.
296
337
  */
@@ -299,13 +340,16 @@ export interface RunFrame {
299
340
  frame: string;
300
341
  }
301
342
  /**
302
- * One run. Apart from `run_id`, each field is the `run_task` argument or the CLI flag of the same name.
343
+ * One run: the run's arguments, and what the server needs to talk to the client about it.
303
344
  *
304
345
  * The reply is the `RunResult`. No API key is among the fields: model and browser keys come from the
305
346
  * environment the server inherited.
306
347
  */
307
348
  export interface RunParams {
308
349
  run_id: string;
350
+ secrets?: SecretRef[];
351
+ frames?: boolean;
352
+ until?: boolean;
309
353
  task: string;
310
354
  start?: string | null;
311
355
  context?: string | null;
@@ -318,12 +362,11 @@ export interface RunParams {
318
362
  output_schema?: {
319
363
  [k: string]: unknown;
320
364
  } | null;
321
- secrets?: SecretRef[];
322
- frames?: boolean;
323
- until?: boolean;
324
365
  downloads?: string | null;
325
366
  record?: string | null;
326
- cursor?: boolean;
367
+ recipe?: string | null;
368
+ save_recipe?: string | null;
369
+ cursor?: boolean | null;
327
370
  local?: boolean;
328
371
  chrome?: LocalChrome | null;
329
372
  cloud_profile?: string | null;
@@ -334,7 +377,13 @@ export interface RunParams {
334
377
  foreground?: boolean;
335
378
  proxy_country?: string | null;
336
379
  viewport?: [number, number] | null;
337
- cloud_allow_resizing?: boolean;
380
+ cloud_extensions?: string[];
381
+ cloud_timeout_minutes?: number | null;
382
+ allowed_origins?: string[] | null;
383
+ fetch?: boolean;
384
+ browser?: boolean;
385
+ extension?: boolean;
386
+ extension_browser?: string | null;
338
387
  }
339
388
  export interface SecretRef {
340
389
  name: string;
@@ -366,6 +415,10 @@ export interface RunResult {
366
415
  * The sign-in or bot wall a `needs_login` or `blocked` run stopped at, when the page showed one.
367
416
  */
368
417
  wall: Wall | null;
418
+ /**
419
+ * The browser the run drove, and how it reached it; none when it read every page over HTTP.
420
+ */
421
+ browser: BrowserUsed | null;
369
422
  }
370
423
  /**
371
424
  * The wall a `needs_login` or `blocked` run stopped at, typed so a caller can route it without parsing `error`.
@@ -430,7 +483,7 @@ export declare const Method: {
430
483
  readonly RUN_CANCEL: 'run/cancel';
431
484
  readonly SHUTDOWN: 'shutdown';
432
485
  };
433
- export declare const PROTOCOL_VERSION = 1;
486
+ export declare const PROTOCOL_VERSION = 2;
434
487
  export declare const ServerMethod: {
435
488
  readonly RUN_EVENT: 'run/event';
436
489
  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 = 2;
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,7 +1,7 @@
1
1
  import { type OutputSchema } from './output.ts';
2
2
  import type { Authorization, BrowserEvent, 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
  };
@@ -25,7 +25,10 @@ export interface BrowserOptions {
25
25
  /** The two-letter country a cloud browser browses from. */
26
26
  proxyCountry?: string;
27
27
  viewport?: [width: number, height: number];
28
- cloudAllowResizing?: boolean;
28
+ /** Up to three IDs of ready extensions on the Browser Use Cloud account, loaded into a cloud browser. */
29
+ cloudExtensions?: string[];
30
+ /** How long a cloud browser may live, in minutes: 15 when none is given, and the service allows up to 240. */
31
+ cloudTimeoutMinutes?: number;
29
32
  }
30
33
  export interface Attachment {
31
34
  name: string;
@@ -70,8 +73,29 @@ export interface RunOptions extends PerRun<BrowserOptions> {
70
73
  downloads?: string;
71
74
  /** Where to write a video of the run. The server needs ffmpeg for it. */
72
75
  record?: string;
73
- /** Draw visual cursor feedback for visible local Chrome on Linux X11 with Cua Driver. */
76
+ /** Replay a recipe file and heal unmatched steps. */
77
+ recipe?: string;
78
+ /** Save completed steps to a recipe file. */
79
+ saveRecipe?: string;
80
+ /** 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
81
  cursor?: boolean;
82
+ /**
83
+ * The only `http(s)://host[:port]` origins whose documents the run may open, read and control, each exact. A
84
+ * navigation, redirect, frame or popup elsewhere is refused before it is sent. It scopes documents, not the
85
+ * network, and a scoped run sends no frames and cannot `record`. Without it the run is unscoped.
86
+ */
87
+ allowedOrigins?: string[];
88
+ /** Read every page over HTTP and start no browser, for a task that only reads. */
89
+ fetch?: boolean;
90
+ /** Start a browser from the first step, rather than reading over HTTP until the task needs one. */
91
+ browser?: boolean;
92
+ /**
93
+ * Run in the user's own Chrome, signed in as they are, through the fastbrowse extension
94
+ * (`fastbrowse extension install`). With no browser connected the run ends `unavailable` before any spend.
95
+ */
96
+ extension?: boolean;
97
+ /** Which browser the extension is connected in, by the label its popup shows. Implies `extension`. */
98
+ extensionBrowser?: string;
75
99
  secrets?: Secrets;
76
100
  /** Called with the address the run ended on. Anything but true keeps the run from `complete`. */
77
101
  until?: (url: string) => MaybePromise<boolean>;
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) {
@@ -28,7 +28,8 @@ function browserFields(options) {
28
28
  foreground: options.foreground,
29
29
  proxy_country: options.proxyCountry,
30
30
  viewport: options.viewport,
31
- cloud_allow_resizing: options.cloudAllowResizing,
31
+ cloud_extensions: options.cloudExtensions,
32
+ cloud_timeout_minutes: options.cloudTimeoutMinutes,
32
33
  });
33
34
  }
34
35
  /** The browser every run of an instance uses, as the fields of a `run` request. */
@@ -53,7 +54,14 @@ export function runParams(runId, task, defaults, options) {
53
54
  output_schema: options.output && wireSchema(options.output),
54
55
  downloads: options.downloads,
55
56
  record: options.record,
57
+ recipe: options.recipe,
58
+ save_recipe: options.saveRecipe,
56
59
  cursor: options.cursor,
60
+ allowed_origins: options.allowedOrigins,
61
+ fetch: options.fetch,
62
+ browser: options.browser,
63
+ extension: options.extension,
64
+ extension_browser: options.extensionBrowser,
57
65
  secrets: options.secrets?.refs,
58
66
  // The wire carries whether a callback is held, and the callback stays here.
59
67
  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.10.0",
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.10.0",
31
+ "@fastbrowse/darwin-x64": "0.10.0",
32
+ "@fastbrowse/linux-arm64": "0.10.0",
33
+ "@fastbrowse/linux-x64": "0.10.0",
34
+ "@fastbrowse/win32-x64": "0.10.0"
35
35
  }
36
36
  }