Docs

When the explorer asks a person

Which element, what value, may it follow a host, is it done: how questions and answers travel.

The exploring agent runs on its own, but a site has things no map can tell it: a promo code that only the team knows, a link that leaves the site on purpose, a page where two models disagree about whether the goal is reached. Instead of giving up, the explorer files a question, parks that journey and carries on with the others. The person answers from the workbench; the journey resumes where it stopped, and what was answered is kept so the next exploration does not ask again.

What it asks

Every question carries a screenshot of the page the explorer is on. Before it is taken, input values and text that contain any of the project's secret values are blanked, and the values are put back after. The screenshot is a JPEG small enough to travel on a heartbeat; it is deleted once the question is answered or closed.

Limits keep it from flooding anyone: two questions per journey, ten per exploration. Past the limit the explorer does what it did before: refuses the form, avoids the element, ends the journey as stuck.

How it travels

The engine keeps a desk of questions (packages/flowqa-explorer/src/questions.mjs). A journey that asks calls ask(); the engine takes the screenshot, files the question and tells the scheduler, which starts the next journey while this one waits. The desk's unsent questions ride on the next heartbeat to the API, which stores them (QaExplorationQuestion) and returns, on every heartbeat, the answers given so far. The desk resolves the waiting journey with its answer.

A heartbeat that failed sends its questions again. When every journey has run or parked, the engine waits up to thirty minutes for the rest of the answers, then expires the desk: parked journeys get null and finish the way they would have alone. Cancelling the exploration expires the desk at once.

The person's side:

• GET /v1/projects/:p/qa/explorations/:id lists questions and counts open_questions; the exploration list carries open_questions per row.
• GET .../questions/:qid/screenshot returns the image as { data, content_type }.
• POST .../questions/:qid/answer takes choice, value and secret, allow, yes, note, give_up, and remember (default true); the API checks the fields against the question's kind.

Open questions expire when the exploration ends, whichever way it ends.

What is kept

With remember on (the default):

• a what_value answer becomes a project variable for the environment, secret unless the person said otherwise;
• an allowed host joins the environment's allowed hosts in the project configuration;
• a note on a which_one or am_i_there answer lands under "From the team" on the page's site note (or the README when the page has no note), where the explorer reads it on every later visit.

If a value cannot be stored (for example the server has no FLOWQA_INPUT_KEY), the answer still reaches the engine and the response says why it was not kept.

In the workbench

The exploration dialog shows open questions above the progress, newest journeys first, each with its screenshot and the controls for its kind. An answer being typed survives the dialog's polling. While the dialog is closed, the Explore button carries a count of open questions and a new question raises a toast with a way into the dialog. Answered questions stay in the dialog as one line each.

Runs on the desktop too

A local exploration goes through the same desk: the desktop relays the heartbeat to the API, so questions and answers travel exactly as they do from a cloud worker.

Taking over the browser (desktop)

On the desktop, a "which element" or "is it done" question offers one more answer: take over the browser. The explorer child reports the page the question was asked on, its URL and its cookies and local storage. The desktop opens the recorder there, signed in as the explorer is, through the recorder's own auth-state setup, and the person does the steps themselves. "Hand back" ends the recording and answers the question with the recorded steps, either to keep exploring or with "goal reached". The explorer replays those steps on its own page (navigate, tap, fill, select, press, waitFor, back, forward, reload; anything else is dropped), records them in the journey as its own, and carries on, or ends the journey as done and writes the assertions. A step that cannot be replayed ends the journey as stuck with the reason, and nothing of the hand-back is recorded.

The route is the recorder's: POST /api/record-edit/takeover with { exploration, question } opens it, POST /api/record-edit/hand-back with { session, done } answers. On the web both say that the desktop app is needed. The API side is the ordinary answer route with steps (valid FlowQA steps, at most 80) and done.

Before any question: a site behind a gate

A preview password or a sign-in that stands in front of every page is not something the explorer asks about mid-journey. The map phase notices it: when the crawl collapses to one page with a password field, the exploration stops with a message naming the page and what it asks for. The remedy is a shared opening: record the steps that pass the gate once, keep the password in a secret variable, and choose that opening under Opening when starting the exploration; the map then starts beyond it. If an opening was chosen and the gate still shows, the message says so and points at the opening's steps and the variable values for that environment. Nothing is written to the site notes from a map that stopped at a gate.