@jobshimo/browser-link 0.23.14 → 0.25.0

package/dist/agent-instructions/content.js

@@ -184,8 +184,40 @@ function body() {
         '  working notes and pass as `since_id` next call. One variable. The',
         '  server does not maintain per-agent cursors.',
         '',
+        '### BULK WORK — `flow` + `repeat`, NEVER a loop inside `evaluate`',
+        '',
+        '"Click every element matching X until the list drains" is a',
+        '`browser.flow` with a `repeat` step, not an `evaluate` loop:',
+        '',
+        '```',
+        '{ repeat: { steps: [{ click: { selector: ".row .delete" } }],',
+        '            max_iterations: 200, while_found: ".row", delay_ms: 250 } }',
+        '```',
+        '',
+        '- Hundreds of iterations in ONE round trip, and every click is still',
+        '  trusted CDP input with the occlusion guard and a recovery snapshot.',
+        '  An `evaluate` loop has NONE of that — `el.click()` is',
+        '  `isTrusted:false`, nothing hit-tests, nothing is recorded.',
+        '- `max_iterations` is REQUIRED and repeats do NOT nest. Inner steps',
+        '  count against the same 20-step ceiling. If the projected budget',
+        '  exceeds 60s the flow is rejected up front — lower `max_iterations`',
+        '  and run the flow again; each call picks up where the last left off',
+        '  when `while_found` still matches.',
+        '- Use `while_found` to decide when to stop, NOT a page counter. It',
+        '  checks for a VISIBLE match before each iteration and reports',
+        '  `stopped_by: "condition"` vs `"max_iterations"`.',
+        '- `delay_ms` throttles between iterations. Use it on anything',
+        '  server-backed.',
+        '- BEFORE an irreversible bulk run (deleting, sending, paying), call',
+        '  the same flow once with `dry_run: true`. It dispatches NOTHING and',
+        '  reports `max_iterations` / `inner_steps` / `delay_ms` /',
+        '  `while_found` / `would_start` per repeat.',
+        '',
         '### LONG-RUNNING WORK — a timed-out `evaluate` KEEPS RUNNING',
         '',
+        'Reach for this only when `flow` + `repeat` genuinely cannot express',
+        'the work (it needs branching, or arbitrary JS per item).',
+        '',
         'A bridge timeout drops the RESPONSE only. The expression itself keeps',
         'running in the page; there is no cancellation path. A timeout reads',
         'like failure, so the reflex is to relaunch — and on irreversible',

package/dist/agent-instructions/content.js.map

@@ -1 +1 @@
-{"version":3,"file":"content.js","sourceRoot":"","sources":["../../src/agent-instructions/content.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"content.js","sourceRoot":"","sources":["../../src/agent-instructions/content.ts"],"names":[],"mappings":"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"}

package/dist/cdp/flow.d.ts

@@ -12,13 +12,15 @@
  *
  * browser.flow step sequencing — the logic behind the composite action
  * tool. Runs a short, declarative list of find/click/type/press/wait_for/
- * drag steps strictly in order, fails fast on the first step that does
- * not succeed, and threads an "implicit target" from a `find` step into
- * the very next click/type/press step that omits its own `selector`. A
- * `drag` step stays OUT of that chain: both of its endpoints are always
- * explicit (selector or coords), so it neither consumes nor sets the
- * implicit target — a pending target survives a drag step untouched for
- * a later click/type/press, exactly like it survives a wait_for.
+ * drag/sleep steps strictly in order, fails fast on the first step that
+ * does not succeed, and threads an "implicit target" from a `find` step
+ * into the very next click/type/press step that omits its own
+ * `selector`. A `drag` step stays OUT of that chain: both of its
+ * endpoints are always explicit (selector or coords), so it neither
+ * consumes nor sets the implicit target — a pending target survives a
+ * drag step untouched for a later click/type/press, exactly like it
+ * survives a wait_for. A `sleep` step is a fixed pause and stays out of
+ * the chain for the same reason: it names no target at all.
  *
  * Deliberately decoupled from any specific transport: every side effect
  * goes through the `FlowDeps` the caller injects. The concrete wiring —
@@ -187,6 +189,67 @@ export interface DragStepResult {
     intercept_received: boolean;
     events_fired: string[];
 }
+/** Hard cap on one `sleep` step's `ms`. Matches the ceiling a single
+ * `wait_for` step may request, so no one step can park the flow longer
+ * than the longest wait already expressible. Out-of-range values are a
+ * validation ERROR rather than a silent clamp: a flow that asked to
+ * throttle by 60s and got 30s would hammer a backend at twice the
+ * intended rate without ever saying so. */
+export declare const MAX_FLOW_SLEEP_MS = 30000;
+/** A fixed pause between steps. `settle_ms` cannot serve this purpose —
+ * it is a quiet-PERIOD wait that returns as soon as the page stops
+ * mutating, so it collapses to nothing on a page that is already idle.
+ * Throttling a repeated action against a rate-limited backend needs a
+ * real delay, and before this step existed the only way to get one was
+ * to drop out of the flow into `browser.evaluate` — losing trusted CDP
+ * input for every action in the loop. */
+export interface SleepStepParams {
+    ms: number;
+}
+/** Hard cap on one `repeat` step's `max_iterations`. The real ceiling in
+ * practice is the flow's own worst-case time budget (a repeat's budget is
+ * `max_iterations × (inner steps + delay)`), which bites long before this
+ * does; this is the backstop that keeps a typo from producing an
+ * absurd projected budget. */
+export declare const MAX_FLOW_REPEAT_ITERATIONS = 500;
+/** Hard cap on a `repeat`'s inter-iteration `delay_ms` — same ceiling a
+ * standalone `sleep` step may request. */
+export declare const MAX_FLOW_REPEAT_DELAY_MS = 30000;
+/** A BOUNDED loop over a sub-sequence of steps.
+ *
+ * `max_iterations` is REQUIRED, deliberately: it is what keeps a flow's
+ * worst-case duration statically computable, which is the whole basis of
+ * the up-front `MAX_FLOW_TIMEOUT_MS` rejection. An unbounded loop would
+ * make that budget unknowable and force the bridge to either park
+ * indefinitely or time out mid-flow — the exact failure the flow budget
+ * exists to prevent.
+ *
+ * `while_found` is the early stop: the loop runs another iteration only
+ * while that selector still matches something VISIBLE in the live DOM.
+ * Making the stop condition declarative is the point — it replaces the
+ * hand-rolled "parse a counter and guess when we are done" pattern that
+ * silently misreads pages whose counters vanish at zero.
+ *
+ * Nesting is rejected: a repeat may not contain a repeat. One bounded
+ * loop keeps the budget arithmetic trivial and the grammar honest.
+ * `steps` may not contain a `repeat`, and inner steps count against the
+ * same `MAX_FLOW_STEPS` ceiling as outer ones. */
+export interface RepeatStepParams {
+    steps: FlowStep[];
+    max_iterations: number;
+    while_found?: string;
+    delay_ms?: number;
+}
+export interface RepeatStepResult {
+    iterations_completed: number;
+    /** `condition` — `while_found` stopped matching. `max_iterations` — the
+     * bound was reached with the condition still true (or with no condition
+     * at all). A failing inner step does not produce a result at all: it
+     * fails the whole flow, like every other step. */
+    stopped_by: 'condition' | 'max_iterations';
+    /** Per-iteration list of the inner steps' compacted results. */
+    iterations: unknown[][];
+}
 export type FlowStep = {
     find: FindStepParams;
 } | {
@@ -199,6 +262,10 @@ export type FlowStep = {
     wait_for: WaitForStepParams;
 } | {
     drag: DragStepParams;
+} | {
+    sleep: SleepStepParams;
+} | {
+    repeat: RepeatStepParams;
 };
 /** Everything the step executor needs from the outside world. `background.ts`
  * (extension) / `cdp/transport.ts` (server) binds each method to the real
@@ -229,6 +296,10 @@ export interface FlowSuccess {
     ok: true;
     steps_completed: number;
     results: unknown[];
+    /** Present ONLY on a `dryRun` projection, where nothing was dispatched
+     * and `steps_completed` is therefore 0. Omitted on a real run, so an
+     * existing consumer sees a byte-identical success shape. */
+    dry_run?: true;
 }
 export interface FlowFailure {
     ok: false;
@@ -239,6 +310,14 @@ export interface FlowFailure {
     recovery_snapshot: unknown;
 }
 export type FlowResult = FlowSuccess | FlowFailure;
+export interface RunFlowOptions {
+    /** Validate and PROJECT the flow without dispatching a single input
+     * event, navigation or pause. Answers the one question that matters
+     * before an irreversible bulk run — "I am about to do this up to N
+     * times; would it even start?" — and is the reason `repeat` and this
+     * flag shipped together. */
+    dryRun?: boolean;
+}
 /**
  * Run a declarative sequence of steps strictly in order, stopping at the
  * first failure. See the module doc comment for the implicit-target and
@@ -249,5 +328,8 @@ export type FlowResult = FlowSuccess | FlowFailure;
  * array may originate from an untrusted JSON payload cast at the wire
  * boundary in `background.ts` (extension) / `cdp/transport.ts` (server),
  * and a malformed entry must fail the flow cleanly rather than throw.
+ *
+ * With `options.dryRun`, the flow is validated and projected instead:
+ * nothing is dispatched, and each entry describes what WOULD run.
  */
-export declare function runFlow(steps: readonly FlowStep[], deps: FlowDeps): Promise<FlowResult>;
+export declare function runFlow(steps: readonly FlowStep[], deps: FlowDeps, options?: RunFlowOptions): Promise<FlowResult>;