fastbrowse 0.8.3 → 0.9.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,9 +8,14 @@ a native binary, so the machine needs no Python.
8
8
 
9
9
  ```sh
10
10
  npm install fastbrowse
11
+ export TYPESAFE_API_KEY=...
11
12
  export OPENROUTER_API_KEY=...
12
13
  ```
13
14
 
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`.
18
+
14
19
  With it npm installs the binary for your platform as an optional dependency: `@fastbrowse/darwin-arm64`,
15
20
  `darwin-x64`, `linux-arm64`, `linux-x64` or `win32-x64`. No install script runs and nothing is downloaded on
16
21
  first use. It needs Node.js 20 or newer, and on Linux it needs glibc.
@@ -41,10 +46,47 @@ try {
41
46
  stopped it in `result.wall`: `kind` is `password`, `one_time_code`, `sign_in` or `bot_check`, with the page's
42
47
  `origin`, the labels of the `fields` it asked for and `seen_at_ms`.
43
48
 
49
+ ## Processes and errors
50
+
51
+ `Fastbrowse.start` starts one fastbrowse process and `run` sends it a task. The process serves one run at a time:
52
+ a second `run` while one is active rejects with the busy error, so start more instances to run side by side.
53
+ `close()` shuts the process down and waits for it, and the process also exits when yours does.
54
+
55
+ `run` rejects when no run took place or none finished: with `RpcError` when the server refuses the request before
56
+ a browser opens (a bad option, a missing key, a busy server), with `AbortError` when `signal` stopped the run, and
57
+ with `ProcessExitedError` when the process is gone. It also rejects with `OutputValidationError` when a run
58
+ finished but its data fails the `output` schema. A run that fails after it starts, including one whose
59
+ callback throws, resolves with status `error`.
60
+
61
+ ## Options
62
+
63
+ The result is the `RunResult` the Python library returns. Its fields keep their Python names, such as
64
+ `final_url`, since the types are generated from the protocol's schema; the options are camelCase.
65
+
66
+ `output` is `data` after a Zod (4.2 or newer) or ArkType schema's validation and transforms, or a Valibot schema
67
+ wrapped by `@valibot/to-json-schema`, typed as the schema's output. Data the schema refuses rejects with
68
+ `OutputValidationError`, which carries the result. A plain JSON Schema object is accepted too; `output` is then
69
+ `data`, typed `unknown`. The server accepts nested objects, arrays, `enum`, `const` and optional values and refuses
70
+ any other keyword by name, but a run fills only a flat object of required string, number, integer and boolean
71
+ fields. With any other field it ends `unverified` with no data.
72
+
73
+ `run` also takes `context`, `inputs`, `attachments` as bytes, `downloads`, `record`, `onFrame` (JPEG frames of the
74
+ 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.
77
+ `env` in `Fastbrowse.start` adds to the environment the process inherits.
78
+
79
+ ## Platforms
80
+
81
+ There is no binary for Alpine or another musl system, and none for a platform outside the five. There
82
+ `Fastbrowse.start` rejects with an error that names the platform; name a binary of your own with `binaryPath` or
83
+ `FASTBROWSE_BINARY`. The macOS binaries carry an ad-hoc signature and are not notarized, which a Mac that allows
84
+ programs only by the team that signed them refuses. The Windows binary is not signed. Bun and Deno are untested.
85
+
44
86
  ## The rest
45
87
 
46
88
  [Use it from JavaScript](https://github.com/agent-labs-dev/fastbrowse#use-it-from-javascript) in the repository
47
- README covers output typed by a Zod or JSON Schema, secrets your own code resolves, the `until` check, step
48
- events, live frames and stopping a run with an `AbortSignal`.
89
+ README has a fuller example: output typed by a Zod schema, secrets your own code resolves, the `until` check,
90
+ step events and stopping a run with an `AbortSignal`.
49
91
 
50
92
  MIT licence.
package/dist/callbacks.js CHANGED
@@ -111,7 +111,6 @@ function endedBy(failure) {
111
111
  citations: [],
112
112
  error: failure,
113
113
  final_url: null,
114
- would_fire: [],
115
114
  recordings: [],
116
115
  wall: null,
117
116
  };
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, StepEvent, StepFact, StepResult, } from './protocol.ts';
4
+ export type { Artifact, BrowserEvent, BudgetStop, 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';
@@ -21,7 +21,6 @@ export type ServerMethod = 'run/event' | 'run/frame' | 'run/until' | 'secrets/re
21
21
  export type Operation = 'click' | 'hover' | 'drag' | 'fill' | 'select' | 'enter' | 'escape' | 'scroll' | 'scroll_up' | 'back' | 'switch_tab' | 'upload' | 'dialog' | 'read' | 'done' | 'escalate' | 'navigate';
22
22
  export type StepOutcome = 'executed' | 'covered' | 'stale' | 'failed';
23
23
  export type Status = 'complete' | 'unverified' | 'needs_confirmation' | 'needs_login' | 'blocked' | 'needs_input' | 'stuck' | 'budget_exceeded' | 'observation_limit' | 'unavailable' | 'error';
24
- export type Tripwire = 'no_progress' | 'action_repetition' | 'plan_stagnation';
25
24
  /**
26
25
  * What a sign-in or bot wall asks of the person who has to get the run past it.
27
26
  */
@@ -259,6 +258,10 @@ export interface StepResult {
259
258
  */
260
259
  page_changed: boolean | null;
261
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[];
262
265
  }
263
266
  export interface StepFact {
264
267
  text: string;
@@ -271,6 +274,23 @@ export interface StepFact {
271
274
  reader: FactReader;
272
275
  deep_link: string | null;
273
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
+ }
274
294
  /**
275
295
  * The params of `run/frame`: the active tab as it looked a moment ago. Sent only to a run that set `frames`.
276
296
  */
@@ -338,10 +358,6 @@ export interface RunResult {
338
358
  * Where the browser was last observed; what a caller checks when the task was to arrive somewhere.
339
359
  */
340
360
  final_url: string | null;
341
- /**
342
- * Shadow tripwires retain each occurrence so eval counts do not depend on logging configuration.
343
- */
344
- would_fire: Tripwire[];
345
361
  /**
346
362
  * The videos this run finished writing, captioned then plain; empty when it recorded nothing or encoding failed.
347
363
  */
package/dist/protocol.js CHANGED
@@ -1,5 +1,5 @@
1
- // Generated from the models in src/fastbrowse/protocol.py and src/fastbrowse/models.py.
2
- // Do not edit: change the models, then run `npm run generate:sdk`.
1
+ // Generated from protocol/schema.json, which crates/fastbrowse-core/src/protocol.rs writes.
2
+ // Do not edit: change the types there, then run `npm run generate:sdk`.
3
3
  export const ErrorCode = {
4
4
  PARSE_ERROR: -32700,
5
5
  INVALID_REQUEST: -32600,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "fastbrowse",
3
- "version": "0.8.3",
3
+ "version": "0.9.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.8.3",
31
- "@fastbrowse/darwin-x64": "0.8.3",
32
- "@fastbrowse/linux-arm64": "0.8.3",
33
- "@fastbrowse/linux-x64": "0.8.3",
34
- "@fastbrowse/win32-x64": "0.8.3"
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"
35
35
  }
36
36
  }