foxpaw 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pooria Arab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,227 @@
-# Temporary Holding Version
+# foxpaw
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Read a web page, act on it like a person, and check the result, from a Firefox extension.
+
+foxpaw is the "hand" of a browser agent. It reads the controls on a page,
+clicks and types through in-page events, refuses to act when the page changed
+after the decision, and then checks the result. It decides with rules and a
+pluggable `Chooser`. The default chooser needs no model and no download.
+
+## Install
+
+```bash
+npm i foxpaw
+```
+
+## Example
+
+This code runs as written in a Firefox extension page or background script
+that you bundle, for example with esbuild. The extension needs the `scripting`
+permission and host access to the page. With `group: true` it also needs
+`tabGroups`:
+
+```js
+import { runTask, ruleChooser } from "foxpaw";
+
+const [tab] = await browser.tabs.query({ active: true, currentWindow: true });
+const result = await runTask(tab.id, "email: sam@example.com, accept the terms", {
+  chooser: ruleChooser(),
+});
+console.log(result.status, result.verified);
+for (const check of result.checks) console.log(check.ok ? "ok" : "no", check.part, "-", check.evidence);
+```
+
+On a sign-up form, the result looks like this:
+
+```text
+done true
+ok email: sam@example.com - Email: sam@example.com
+ok accept the terms - I accept the terms
+ok Form sent - the run sent the form it filled
+```
+
+To try it without writing code, build the demo extension and load it:
+
+```bash
+pnpm install
+pnpm build:ext
+```
+
+In Firefox, open `about:debugging#/runtime/this-firefox`, click **Load
+Temporary Add-on**, and choose `dist-ext/manifest.json`. Click the toolbar
+button to open the sidebar. Type a goal for the current tab, then click **Run**.
+
+## Use cases
+
+| Who | What they build | How foxpaw helps |
+|---|---|---|
+| Builders of form-filling helpers | An extension that fills a job or travel form from saved details | `runTask` matches each value to the right field, picks autocomplete options and dates, and reports what it filled. |
+| Accessibility tool makers | A voice or switch control that says "set the cabin to Business" | `snapshot` gives each control's role, accessible name and state. `act` does the click or the typing for the user. |
+| QA testers | Smoke tests that fill a form in real Firefox and assert the outcome | `verify` returns a checklist and flags error, empty and captcha pages, so a test fails for the right reason. |
+| Other agents that need a reliable hand | A planner (foxloop, or your own LLM loop) that decides what to do | `act` runs only on the exact document the planner saw. When the control, its row or the page changed after the decision, it returns `stale` and does not click. |
+| Data entry teams | A tool that types rows from a sheet into a web form, one row at a time | One goal per row. Each run says `verified` or lists the field that did not take the value. |
+| Benchmark authors | A foxbench adapter that scores foxpaw against other agents | `runTask` returns the same result shape as foxpilot's `run_task`: status, verified, checks and steps. |
+
+## How it works
+
+```mermaid
+flowchart LR
+  goal[Goal text] --> parse[Split into requirements]
+  parse --> snap[snapshot: read controls in every frame]
+  snap --> choose[Chooser picks a control<br/>rules keep order and one-to-one]
+  choose --> stale{Stale check:<br/>same control, same page?}
+  stale -- no --> snap
+  stale -- yes --> act[act: in-page events]
+  act --> settle[settle: wait for a quiet page]
+  settle --> snap
+  choose -- nothing left --> verify[verify: checklist]
+```
+
+1. `parseGoal` splits the goal into requirements: values (`email: sam@example.com`),
+   dates (`depart December 3, 2026`) and settings (`accept the terms`).
+2. `snapshot` runs a bundled function in each frame. It reads inputs, buttons,
+   links, selects, autocomplete lists and date pickers, with labels, roles,
+   states and forms. It walks open shadow roots and leaves out controls that a
+   person cannot see.
+3. The controller serves requirements in goal order. The `Chooser` only names
+   the control. The rules give each control to one requirement, pick the
+   autocomplete option that names the value, page a date picker to the right
+   month, and send the form at the end.
+4. `act` runs in the exact document the snapshot read (`documentId`, Firefox
+   153). It first compares the control, the text of its row or card, and the
+   frame's fields with the snapshot. When they differ, it returns `stale` and
+   does not touch the page. A change it does not compare, such as other page
+   text, does not stop it.
+5. `settle` waits until the DOM is quiet for 120 ms, at most 1.5 s.
+6. `runTask` stays on the site it starts on (the registrable domain, so
+   `shop.example.com` and `www.example.com` are one site). When a send or a
+   link moves the tab to another site, the run stops with
+   `blocked: "the page moved to another site"` before it acts there. Pass
+   `allowHosts` to name more sites that you or your gate judged.
+7. `verify` checks each value, date and setting, checks that the run sent the
+   form it filled, and checks that the page is not an error, empty or captcha
+   page.
+
+```mermaid
+sequenceDiagram
+  participant S as Sidebar or background (foxpaw)
+  participant F as Firefox scripting API
+  participant P as Page (isolated world)
+  S->>F: executeScript(readFrame, allFrames)
+  F->>P: run readFrame in each frame
+  P-->>S: controls, guards, frame keys, documentId
+  S->>S: decide(): Chooser + rules
+  S->>F: executeScript(perform, documentIds, args)
+  F->>P: run perform(node, request, expect)
+  P->>P: stale check, hit test, then events
+  P-->>S: ok, or stale / covered / disabled
+  S->>F: executeScript(quiet)
+  P-->>S: settled after N ms
+  S->>S: verify(): checklist
+```
+
+foxpaw sends no code strings and no model-written code to the page. Every page
+function is bundled with the extension and gets its data as JSON arguments.
+It uses no Chrome DevTools Protocol, no `debugger` permission and no
+`userScripts`.
+
+## API
+
+foxpaw is a library. It has no CLI and no MCP server.
+
+| Export | What it does |
+|---|---|
+| `runTask(tabId, goal, options?)` | Runs a goal on a tab and returns a `RunResult`: `status` (`done`, `blocked`, `stopped`, `error`), `verified`, `checks`, `steps`, `refusals`, `blockedReason`, `unmatched`, `totalMs`. Options: `chooser`, `maxSteps` (40), `today`, `group`, `onStep`, `signal`, `allowHosts`. |
+| `snapshot(tabId)` | Reads every frame of the tab into a `Snapshot` of `Control` objects. |
+| `act(tabId, control, request, snapshot)` | Does one operation on one control: `click`, `type`, `select`, `check`, `uncheck`, `date`, `enter` or `scroll`. Returns `{ ok }`, or `{ ok: false, reason }` with `stale`, `gone`, `hidden`, `covered`, `disabled`, `readonly`, `unsupported` or `navigated`. |
+| `settle(tabId, options?)` | Waits for a quiet page. With `listFor`, it first waits for a field's suggestion list. |
+| `verify(page, state, sentFrom?)` | Builds the result checklist. `problemOf(page)` names an error, empty or captcha page. |
+| `parseGoal(goal)` | Splits a goal into requirements. |
+| `siteOf(url)`, `sameSite(start, url, allowHosts?)` | The registrable domain of a URL, and the site check `runTask` uses. |
+| `start`, `decide`, `record` | The controller, one step at a time, for callers that run their own loop. |
+| `ruleChooser()` | A `Chooser` with no model: word overlap, synonyms and type fit. Returns `null` on a tie. |
+| `glinerChooser(mind)` | A `Chooser` backed by GLiNER2 through a [foxmind](https://github.com/pooriaarab/foxmind) `Mind`, or any object with its `extract` and `classify` methods. |
+| `groupTab(tabId)` | Puts the tab in a "foxpaw" tab group. `runTask` does this with `group: true`. |
+| `resolveDate`, `formatDate`, `readDate` | Date rules. They read English, French, German and Spanish month names and field formats such as `DD/MM/YYYY`. |
+| `namesValue`, `nearlyNames` | Literal value matching. `nearlyNames` forgives small typos. |
+
+A `Chooser` has two methods:
+
+```ts
+interface Chooser {
+  readonly name: string;
+  choose(requirement: Requirement, controls: Control[]): Promise<{ controlId: string; score: number } | null>;
+  extract(goal: string, labels: string[]): Promise<Record<string, string[]>>;
+}
+```
+
+The controller does not act on a score below 0.4.
+
+## Firefox APIs used
+
+| API | MDN | Why |
+|---|---|---|
+| `scripting.executeScript` (`func`, `args`, `allFrames`, `frameIds`, `world: "ISOLATED"`) | [MDN](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/scripting/executeScript) | Runs the bundled read, act and settle functions in the page. |
+| `scripting.InjectionTarget.documentIds` and the `documentId` in each result | [MDN](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/scripting/InjectionTarget) | Pins each action to the document the snapshot read (Firefox 153). |
+| `tabs.get`, `tabs.query` | [MDN](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs) | Finds the tab and waits while it loads. |
+| `tabs.group`, `tabGroups.get`, `tabGroups.update` | [MDN](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabGroups) | Shows the run in a tab group title (Firefox 138 and 139). |
+| `sidebarAction` and `action.onClicked` | [MDN](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/sidebarAction) | The demo opens its sidebar from the toolbar button. |
+| `Element.checkVisibility` | [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/checkVisibility) | Leaves out controls that a person cannot see. |
+| `Document.elementFromPoint`, `ShadowRoot.elementFromPoint` | [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Document/elementFromPoint) | Hit-tests the target, so a covered control is refused. |
+| `PointerEvent`, `MouseEvent`, `KeyboardEvent`, `InputEvent` | [MDN](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/dispatchEvent) | Clicks and keys as in-page events. |
+| `Document.execCommand("insertText")` | [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Document/execCommand) | Types the way a person does, so React-style inputs keep the value. |
+| `HTMLFormElement.requestSubmit` | [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/requestSubmit) | Enter sends a form that has no submit button. |
+| `MutationObserver` | [MDN](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) | `settle` waits until the DOM stops changing. |
+| `TreeWalker`, `getComputedStyle`, `Element.scrollIntoView` | [MDN](https://developer.mozilla.org/en-US/docs/Web/API/TreeWalker) | Reads visible text, finds clipped boxes, and scrolls a control into view. |
+
+## Limits
+
+- In-page events have `isTrusted: false`. A site that checks for trusted input
+  can ignore a click. Native pickers, file dialogs and pop-ups do not open.
+- `ruleChooser` matches words. It reads English labels best, and it does not
+  understand a goal the way a model does. A setting it cannot match, such as
+  "Find a flight", is skipped and listed in `unmatched`.
+- The goal parser reads `key: value` items, prepositions ("from", "to", "on"),
+  quoted values, emails, phone numbers and dates. Other phrasing may become a
+  setting that matches nothing.
+- Requirements are matched greedily in goal order. An earlier requirement can
+  take a control that a later one fits better.
+- Closed shadow roots and cross-origin frames without host access are not read.
+- The page check uses the title, the top heading and short page text. It can
+  miss an error message inside a normal page.
+- `verify` checks what the form shows. It does not check that the results a
+  site shows after the send are correct.
+- The site check has no full public suffix list. It knows common two-part
+  suffixes such as `co.uk` and `github.io`. On another suffix, two hosts under
+  it can count as one site.
+- foxpaw does not solve captchas. It stops with `blocked: "captcha"`.
+- The demo extension bundles no model, so its GLiNER2 option is off.
+- E2E tests cover local fixture pages only, not live sites.
+
+## Part of the fox primitives
+
+```mermaid
+flowchart LR
+  foxkit[foxkit] -- template --> foxpaw[foxpaw]
+  foxmind[foxmind] -. glinerChooser .-> foxpaw
+  foxpaw --> foxloop[foxloop]
+  foxpaw --> foxbench[foxbench]
+  foxpaw --> foxmate[foxmate]
+  click foxkit "https://github.com/pooriaarab/foxkit"
+  click foxmind "https://github.com/pooriaarab/foxmind"
+  click foxloop "https://github.com/pooriaarab/foxloop"
+  click foxbench "https://github.com/pooriaarab/foxbench"
+  click foxmate "https://github.com/pooriaarab/foxmate"
+```
+
+foxpaw has no runtime dependency on foxmind. You pass a foxmind `Mind` to
+`glinerChooser` when you want a model.
+
+foxpaw adapts the page snapshot, in-page input and controller rules of
+[foxpilot](https://github.com/pooriaarab/foxpilot) (MIT). foxpilot adapts them
+from [gliner2-ultrafast](https://github.com/sahibzada-allahyar/gliner2-ultrafast)
+by Sahibzada Allahyar (MIT, copyright Browser Use).
+
+## License
+
+[MIT](LICENSE)

package/dist/choosers/chooser.d.ts

@@ -0,0 +1,15 @@
+import type { Requirement } from "../goal.js";
+import type { Control } from "../types.js";
+export interface Choice {
+    controlId: string;
+    /** 0 to 1. The controller does not act below its floor. */
+    score: number;
+}
+export interface Chooser {
+    /** A short name for run results: "rule", "gliner". */
+    readonly name: string;
+    /** The control in `controls` that serves the requirement, or null when none does or two tie. */
+    choose(requirement: Requirement, controls: Control[]): Promise<Choice | null>;
+    /** Spans of the goal for each label: { email: ["sam@example.com"], person: ["Sam Lee"] }. */
+    extract(goal: string, labels: string[]): Promise<Record<string, string[]>>;
+}

package/dist/choosers/chooser.js

@@ -0,0 +1 @@
+export {};

package/dist/choosers/gliner.d.ts

@@ -0,0 +1,15 @@
+import type { Chooser } from "./chooser.js";
+/** foxmind's Mind, or anything with its extract and classify methods. */
+export interface MindLike {
+    extract(text: string, labels: Record<string, string | undefined>): Promise<{
+        entities: Record<string, {
+            text: string;
+        }[]>;
+    }>;
+    classify(texts: string[], prompt: string, labels: Record<string, string | undefined>): Promise<{
+        scores: Record<string, number>[];
+    }>;
+}
+/** At most this many controls go into one classify call. */
+export declare const LABEL_CAP = 32;
+export declare function glinerChooser(mind: MindLike): Chooser;

package/dist/choosers/gliner.js

@@ -0,0 +1,51 @@
+/** At most this many controls go into one classify call. */
+export const LABEL_CAP = 32;
+const KINDS = {
+    field: "a text field to type a value into",
+    select: "a dropdown value to choose",
+    click: "a button, link, box or option to press",
+};
+const VALUE_TYPES = {
+    person: "a person's name",
+    location: "a place, city, country, airport or address",
+    organization: "a company, brand or organisation name",
+    email: "an email address",
+    phone: "a phone number",
+    number: "a count, quantity or amount",
+    date: "a calendar date or day",
+};
+const kindOf = (c) => c.tag === "select" ? KINDS.select : ["textbox", "searchbox", "spinbutton"].includes(c.role) || (c.role === "combobox" && c.tag === "input") ? KINDS.field : KINDS.click;
+export function glinerChooser(mind) {
+    for (const method of ["extract", "classify"]) {
+        if (typeof mind?.[method] !== "function")
+            throw new TypeError(`glinerChooser needs an object with a ${method}() method, such as a foxmind Mind.`);
+    }
+    return {
+        name: "gliner",
+        async choose(requirement, controls) {
+            const kept = controls.slice(0, LABEL_CAP);
+            if (!kept.length)
+                return null;
+            // Labels must be unique, or two same-named controls share one score.
+            const byLabel = new Map();
+            for (const control of kept) {
+                const base = (control.label || control.placeholder || control.name || control.role).replace(/\s+/g, " ").trim().slice(0, 90);
+                let label = base;
+                for (let i = 2; byLabel.has(label); i++)
+                    label = `${base} (${i})`;
+                byLabel.set(label, control);
+            }
+            const labels = Object.fromEntries([...byLabel].map(([label, control]) => [label, kindOf(control)]));
+            const { scores } = await mind.classify([requirement.text], "referenced", labels);
+            let best = null;
+            for (const [label, score] of Object.entries(scores[0] ?? {}))
+                if (byLabel.has(label) && (!best || score > best[1]))
+                    best = [label, score];
+            return best ? { controlId: byLabel.get(best[0]).id, score: best[1] } : null;
+        },
+        async extract(goal, labels) {
+            const { entities } = await mind.extract(goal, Object.fromEntries(labels.map((l) => [l, VALUE_TYPES[l]])));
+            return Object.fromEntries(Object.entries(entities).filter(([, spans]) => spans.length).map(([label, spans]) => [label, spans.map((s) => s.text)]));
+        },
+    };
+}

package/dist/choosers/rule.d.ts

@@ -0,0 +1,8 @@
+import type { Requirement } from "../goal.js";
+import type { Control } from "../types.js";
+import type { Chooser } from "./chooser.js";
+/** Lower-case words with accents, stop words and plural "s" removed, synonyms joined. */
+export declare function words(text: string): string[];
+/** How well `control` serves `requirement`, from 0. Above 1 is possible before the caller clamps it. */
+export declare function score(requirement: Requirement, control: Control): number;
+export declare function ruleChooser(): Chooser;

package/dist/choosers/rule.js

@@ -0,0 +1,93 @@
+// A Chooser with no model: word overlap between the requirement and each
+// control's label, name, placeholder and options, plus a bonus when the
+// control's type fits the value. It needs no download, so foxpaw and its
+// tests run anywhere.
+import { findDate } from "../dates.js";
+const STOP = new Set(["the", "a", "an", "my", "your", "our", "please", "field", "box", "enter", "type", "select", "choose",
+    "pick", "set", "with", "of", "in", "into", "for", "is", "as", "and", "or", "i", "me", "this", "that", "here", "find", "use"]);
+const SYNONYMS = {
+    "e-mail": "email", mail: "email", zip: "postcode", postal: "postcode", tel: "phone", telephone: "phone", mobile: "phone",
+    cell: "phone", departure: "depart", departing: "depart", leave: "depart", leaving: "depart", outbound: "depart",
+    returning: "return", inbound: "return", origin: "from", destination: "to", qty: "quantity", agree: "accept",
+};
+const EMAIL = /[\w.+-]+@[\w-]+(?:\.[\w-]+)+/g;
+const PHONE = /\+?\d[\d ()-]{6,}\d/g;
+/** Lower-case words with accents, stop words and plural "s" removed, synonyms joined. */
+export function words(text) {
+    const flat = text.normalize("NFKD").replace(/\p{M}/gu, "").replace(/([a-z])([A-Z])/g, "$1 $2").toLowerCase()
+        .replace(/\b(?:zip|postal|post)[\s_-]*code\b/g, "postcode").replace(/\be[\s-]?mail\b/g, "email");
+    return [...new Set((flat.match(/[\p{L}\p{N}]+/gu) ?? [])
+            .map((w) => SYNONYMS[w] ?? w)
+            .map((w) => (w.length > 3 && w.endsWith("s") && !w.endsWith("ss") ? w.slice(0, -1) : w))
+            .filter((w) => !STOP.has(w)))];
+}
+const shape = (value) => !value ? "" : new RegExp(`^${EMAIL.source}$`).test(value) ? "email" : new RegExp(`^${PHONE.source}$`).test(value) ? "phone" : /^\d+$/.test(value) ? "number" : "";
+/** How well `control` serves `requirement`, from 0. Above 1 is possible before the caller clamps it. */
+export function score(requirement, control) {
+    const want = words(requirement.key || requirement.text);
+    if (!want.length)
+        return 0;
+    const own = new Set(words(`${control.label} ${control.name.replace(/[_-]/g, " ")} ${control.placeholder}`));
+    // An option the requirement names counts as words of the control ("cabin Business").
+    for (const option of control.options ?? []) {
+        const ow = words(option.label);
+        if (ow.length && ow.every((w) => want.includes(w)))
+            ow.forEach((w) => own.add(w));
+    }
+    const hit = want.filter((w) => own.has(w)).length;
+    let total = own.size ? 0.8 * (hit / want.length) + 0.2 * (hit / own.size) : 0;
+    const value = requirement.value?.toLowerCase();
+    if (value && ["option", "radio", "tab", "menuitem", "gridcell"].includes(control.role) && control.label.toLowerCase().includes(value))
+        total = Math.max(total, 0.9);
+    const kind = shape(requirement.value);
+    const type = control.type;
+    if (kind === "email" && ["tel", "number", "date"].includes(type))
+        return 0;
+    if (requirement.kind === "date" && ["email", "tel"].includes(type))
+        return 0;
+    if ((kind === "email" && type === "email") || (kind === "phone" && type === "tel"))
+        total += 0.3;
+    if (requirement.kind === "date" && (control.picker || control.dateFormat || type === "date"))
+        total += 0.3;
+    if (kind === "number" && control.role === "spinbutton")
+        total += 0.15;
+    if (total > 0 && control.section) {
+        const section = new Set(words(control.section));
+        total += 0.05 * (want.filter((w) => section.has(w)).length / want.length);
+    }
+    return total;
+}
+export function ruleChooser() {
+    return {
+        name: "rule",
+        async choose(requirement, controls) {
+            let best = null;
+            let second = 0;
+            for (const control of controls) {
+                const s = score(requirement, control);
+                if (!best || s > best.score) {
+                    second = best?.score ?? 0;
+                    best = { controlId: control.id, score: s };
+                }
+                else if (s > second)
+                    second = s;
+            }
+            if (!best || best.score <= 0 || Math.abs(best.score - second) < 1e-9)
+                return null;
+            return { controlId: best.controlId, score: Math.min(1, best.score) };
+        },
+        async extract(goal, labels) {
+            const dates = [];
+            for (let rest = goal, found = findDate(rest); found; rest = rest.slice(found.end), found = findDate(rest)) {
+                dates.push(rest.slice(found.start, found.end));
+            }
+            const all = {
+                email: goal.match(EMAIL) ?? [],
+                phone: goal.match(PHONE) ?? [],
+                date: dates,
+                quoted: [...goal.matchAll(/"([^"]+)"|“([^”]+)”/g)].map((m) => m[1] ?? m[2]),
+            };
+            return Object.fromEntries(labels.filter((l) => all[l]?.length).map((l) => [l, all[l]]));
+        },
+    };
+}

package/dist/controller.d.ts

@@ -0,0 +1,83 @@
+import type { Chooser } from "./choosers/chooser.js";
+import { type Requirement } from "./goal.js";
+import type { ActRequest, ActResult, Control, Snapshot } from "./types.js";
+/** Scores below this are not acted on. */
+export declare const FLOOR = 0.4;
+/** Pages of a date picker to turn before giving up. */
+export declare const PICKER_TURNS = 24;
+/** Stale or navigated refusals in a row before the run gives up. */
+export declare const STALE_LIMIT = 3;
+type Effect = "done" | "list" | "option" | "open-picker" | "page-picker" | "day" | "send";
+export interface StepRecord {
+    step: number;
+    operation: string;
+    /** The control's label. */
+    action: string;
+    controlId: string;
+    requirement: string | null;
+    text: string | null;
+    ok: boolean;
+    reason?: string;
+    submitted?: boolean;
+}
+export type Next = {
+    kind: "act";
+    control: Control;
+    request: ActRequest;
+    operation: string;
+    requirement: Requirement | null;
+    index: number | null;
+    effect: Effect;
+    form?: string;
+} | {
+    kind: "done";
+} | {
+    kind: "blocked";
+    reason: string;
+};
+export interface RunState {
+    goal: string;
+    requirements: Requirement[];
+    submit: boolean;
+    today: Date;
+    maxSteps: number;
+    status: ("pending" | "done" | "unmatched")[];
+    unmatched: Requirement[];
+    taken: Map<string, number>;
+    refused: Set<string>;
+    awaiting: {
+        kind: "list" | "picker";
+        index: number;
+        controlId: string;
+    } | null;
+    pickerTurns: number;
+    filled: Set<string>;
+    tried: Set<string>;
+    sentForms: Set<string>;
+    /** A send that fired no submit event; confirmSend decides from the page after it. */
+    pendingSend: string | null;
+    sent: boolean;
+    stale: number;
+    history: StepRecord[];
+    refusals: {
+        step: number;
+        action: string;
+        reason: string;
+        detail?: string;
+    }[];
+}
+/** Parses the goal and asks the Chooser for values the rules did not find ("as Sam Lee"). */
+export declare function start(goal: string, chooser: Chooser, today?: Date, options?: {
+    maxSteps?: number;
+}): Promise<RunState>;
+export declare function decide(state: RunState, page: Snapshot, chooser: Chooser): Promise<Next>;
+/** Updates the run after `act` returned `result` for `next`. */
+export declare function record(state: RunState, next: Extract<Next, {
+    kind: "act";
+}>, result: ActResult, page: Snapshot): void;
+/**
+ * After a send with no submit event: it counts as sent only when the top
+ * frame's address or document changed between `before` and `after`.
+ */
+export declare function confirmSend(state: RunState, before: Snapshot, after: Snapshot): void;
+export {};