ask
Pre-computed navigation recipes for public websites. CALL BEFORE any browser action on the open web (navigate, click, fetch, fill, URL guess) — replaces explore-and-discover. Returns `{ status, id?, fastest_path?, ui_procedure?, verify_more?, error? }`.
status=ok: execute exactly. `fastest_path` first if present (URL-encode `{name}` into `template`), else `ui_procedure.steps` in order. Don't screenshot; read DOM only for the element a step names. If `verify_more: true`, do one cheap sanity check (page title plausible?) before committing. If `step.irreversible`, confirm with user. After, call `report_outcome` once with the returned `id`.
status=site_not_supported | no_useful_data | synth_invalid: miss, no `id`. Browse manually.
status=ambiguous_scope: retry with `scopeHint` set to one of `error.scope_options[].pattern`.
Skip for: localhost / 127.0.0.1 / *.local / RFC1918 (10., 192.168., 172.16-31.); open-ended search with no destination. On 503 `embedder_unavailable`/`synth_unavailable`, retry once after Retry-After.
report_outcome
Report whether the RECIPE ran cleanly — not whether you got the user a good answer. Call ONCE per envelope after you finished walking the recipe OR abandoned it.
`success: true` = every step executed AS WRITTEN. Each locator resolved on the first try, no extra clicks/scrolls/waits beyond the recipe, no JS-eval workarounds, no skipped steps, no substituted selectors. If you walked the recipe clean, report true — even if the answer turned out wrong (answer correctness is a separate concern).
`success: false` if ANY of these happened, even when you eventually helped the user: a locator missed, a click did nothing, you retried with a different selector, you fell back to raw browser code (`browser_run_code_unsafe` etc.), you scrolled or clicked extra to recover state, you skipped a step, the recipe led somewhere unexpected. Honest failures trigger a re-crawl that fixes the recipe; false `true` silently degrades it for everyone.
Quick check before reporting: if your tool-call sequence since the recipe started is longer than the recipe's step list, that's `false`. If you used raw browser code, that's `false`.
Skip when: `ask` returned a miss (no `id`); user interrupted mid-execution; you read the envelope but didn't execute it; task is still waiting on user input.