fastbrowse 0.10.0 → 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
@@ -18,8 +18,9 @@ With it npm installs the binary for your platform as an optional dependency: `@f
18
18
  `darwin-x64`, `linux-arm64`, `linux-x64` or `win32-x64`. No install script runs and nothing is downloaded on
19
19
  first use. It needs Node.js 20 or newer, and on Linux it needs glibc.
20
20
 
21
- The binary brings no browser. `local: true` drives the Chrome on your machine. Without it a run starts a
22
- 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`.
23
24
 
24
25
  ## First run
25
26
 
@@ -95,6 +96,8 @@ starts one from the first step; the server refuses the two together. `allowedOri
95
96
  may open, read and control to those exact origins: navigations, redirects, frames and popups elsewhere are refused
96
97
  before they are sent, so a sign-in that redirects through another origin needs it listed too. It scopes documents,
97
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`.
98
101
  `env` in `Fastbrowse.start` adds to the environment the process inherits.
99
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;
100
103
  `recipe` reuses saved values for matching live actions with the same task.
package/dist/addon.d.ts CHANGED
@@ -22,12 +22,8 @@ export interface Addon {
22
22
  protocolVersion(): number;
23
23
  /**
24
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
25
  */
30
- setPdfHelper?(path: string): boolean;
26
+ setPdfHelper(path: string): boolean;
31
27
  }
32
28
  /**
33
29
  * The addon to load: the caller's own path first, then the one the environment names, then the `fastbrowse.node`
@@ -37,8 +33,7 @@ export declare function loadAddon(addonPath: string | undefined, env: NodeJS.Pro
37
33
  /**
38
34
  * Have `addon` read PDFs with the fastbrowse binary `env` resolves to, once its protocol is known to match. A PDF is
39
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
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.
36
+ * is. Without a binary, the addon still runs and says of each PDF that its text went unread.
42
37
  */
43
38
  export declare function readPdfsWith(addon: Addon, env: NodeJS.ProcessEnv, binaryPath?: string): void;
44
39
  /** Runs on the addon, one at a time as the fastbrowse process runs them, so the two modes answer alike. */
package/dist/addon.js CHANGED
@@ -25,12 +25,9 @@ export function loadAddon(addonPath, env) {
25
25
  /**
26
26
  * Have `addon` read PDFs with the fastbrowse binary `env` resolves to, once its protocol is known to match. A PDF is
27
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.
28
+ * is. Without a binary, the addon still runs and says of each PDF that its text went unread.
30
29
  */
31
30
  export function readPdfsWith(addon, env, binaryPath) {
32
- if (typeof addon.setPdfHelper !== 'function')
33
- return;
34
31
  let binary;
35
32
  try {
36
33
  binary = resolveBinary(binaryPath, env);
@@ -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
@@ -113,6 +113,7 @@ function endedBy(failure, spent) {
113
113
  artifacts: [],
114
114
  citations: [],
115
115
  error: failure,
116
+ failure_kind: null,
116
117
  final_url: null,
117
118
  recordings: spent?.recordings ?? [],
118
119
  wall: null,
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, CancellationReceipt, 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';
@@ -3,16 +3,22 @@ export type ArtifactKind = 'download' | 'screenshot' | 'capture';
3
3
  * How a run reached the browser it drove.
4
4
  */
5
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';
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';
7
9
  /**
8
10
  * Who chose a step: Jev, a rule in code, or a saved recipe action confirmed by Jev.
9
11
  */
10
12
  export type Decider = 'jev' | 'code' | 'recipe';
11
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';
12
18
  export type FactReader = 'jev_choice' | 'llm_image';
13
- export type CostComponent = 'jev' | 'llm' | 'browser' | 'proxy';
19
+ export type CostComponent = 'jev' | 'llm' | 'browser' | 'proxy' | 'search';
14
20
  export type CostBasis = 'metered' | 'estimated' | 'bounded' | 'unsettled' | 'unknown';
15
- export type LLMPurpose = 'start' | 'compose' | 'image_read' | 'fill' | 'pages' | 'dates';
21
+ export type LLMPurpose = 'start' | 'compose' | 'image_read' | 'fill' | 'pages' | 'dates' | 'known_pages' | 'recovery_pages' | 'search' | 'unobtainable' | 'groups' | 'action';
16
22
  export type JevPurpose = 'action' | 'authorization' | 'relevance' | 'read' | 'verify' | 'locate';
17
23
  /**
18
24
  * Every code an error reply can carry: the JSON-RPC standard ones, then this protocol's own.
@@ -76,6 +82,14 @@ export interface BrowserUsed {
76
82
  */
77
83
  browser: string | null;
78
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
+ }
79
93
  export interface BudgetStop {
80
94
  resource: 'steps' | 'dollars' | 'seconds' | 'jev_calls' | 'llm_calls';
81
95
  limit: number;
@@ -99,6 +113,7 @@ export interface StepResult {
99
113
  operation: Operation;
100
114
  decided_by: Decider;
101
115
  outcome: StepOutcome;
116
+ failure: StepFailure | null;
102
117
  url: string;
103
118
  /**
104
119
  * Human-readable label of the chosen element; never contains a secret value.
@@ -213,12 +228,22 @@ export interface Evidence {
213
228
  * The `uri` of the `capture` artifact holding the page text `start` and `end` index into, if one was kept.
214
229
  */
215
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[];
216
235
  }
217
236
  export interface SourceControl {
218
237
  role: string;
219
238
  label: string;
220
239
  context: string | null;
221
240
  }
241
+ export interface Link {
242
+ text: string;
243
+ start: number;
244
+ end: number;
245
+ href: string;
246
+ }
222
247
  /**
223
248
  * The client's side of the handshake.
224
249
  *
@@ -321,7 +346,7 @@ export interface RunCancelParams {
321
346
  */
322
347
  export interface RunEvent {
323
348
  run_id: string;
324
- event: StepEvent | BrowserEvent;
349
+ event: StepEvent | BrowserEvent | BrowserWarningEvent;
325
350
  }
326
351
  export interface StepEvent {
327
352
  type: 'step';
@@ -368,6 +393,7 @@ export interface RunParams {
368
393
  save_recipe?: string | null;
369
394
  cursor?: boolean | null;
370
395
  local?: boolean;
396
+ launch?: boolean;
371
397
  chrome?: LocalChrome | null;
372
398
  cloud_profile?: string | null;
373
399
  cdp_url?: string | null;
@@ -384,6 +410,7 @@ export interface RunParams {
384
410
  browser?: boolean;
385
411
  extension?: boolean;
386
412
  extension_browser?: string | null;
413
+ desktop?: string | null;
387
414
  }
388
415
  export interface SecretRef {
389
416
  name: string;
@@ -403,6 +430,10 @@ export interface RunResult {
403
430
  artifacts: Artifact[];
404
431
  citations: Citation[];
405
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;
406
437
  /**
407
438
  * Where the browser was last observed; what a caller checks when the task was to arrive somewhere.
408
439
  */
@@ -483,7 +514,7 @@ export declare const Method: {
483
514
  readonly RUN_CANCEL: 'run/cancel';
484
515
  readonly SHUTDOWN: 'shutdown';
485
516
  };
486
- export declare const PROTOCOL_VERSION = 2;
517
+ export declare const PROTOCOL_VERSION = 3;
487
518
  export declare const ServerMethod: {
488
519
  readonly RUN_EVENT: 'run/event';
489
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 = 2;
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/run.d.ts CHANGED
@@ -1,5 +1,5 @@
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
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> = {
@@ -7,9 +7,11 @@ export type CamelKeys<Model> = {
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. */
@@ -100,10 +102,11 @@ export interface RunOptions extends PerRun<BrowserOptions> {
100
102
  /** Called with the address the run ended on. Anything but true keeps the run from `complete`. */
101
103
  until?: (url: string) => MaybePromise<boolean>;
102
104
  /**
103
- * Called with the browser event and then each step event, in the order the run produced them. Like any
104
- * 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`.
105
108
  */
106
- onEvent?: (event: StepEvent | BrowserEvent) => void;
109
+ onEvent?: (event: StepEvent | BrowserEvent | BrowserWarningEvent) => void;
107
110
  /** Called with JPEG frames of the active tab while the run goes on. Without it the page is never filmed. */
108
111
  onFrame?: (frame: Uint8Array) => void;
109
112
  /**
package/dist/run.js CHANGED
@@ -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,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "fastbrowse",
3
- "version": "0.10.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.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"
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
  }