Bowmark

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?, shortcut?, ui_procedure?, executable?, verify_more?, error? }`. status=ok: execute exactly. `shortcut` first if present — fill each `{name}` in `template` with the value FROM YOUR TASK (using the parameter's `description`/`format` as the shape), URL-encode, navigate. Else `ui_procedure.steps` in order. The recipe is generic: parameter slots and step descriptions describe what to supply ('the destination'), not literal values — you provide the specifics. EXECUTE OPEN-LOOP: the recipe is authoritative, so run it without taking exploratory snapshots, clicks, scrolls, or screenshots to 'verify' or 'look around' — every extra browser action re-reads the entire page, which is the cost the recipe exists to avoid. Read the page ONLY at a `read` step, and only the part it names. Drop back into norm

{
  "type": "object",
  "properties": {
    "site": {
      "type": "string",
      "description": "Registrable domain, optionally followed by a product-surface path — 'google.com', 'docs.stripe.com', 'google.com/maps'. No scheme/port. A path is treated as an implicit scopeHint when it matches a known surface, so you can skip the ambiguous_scope round-trip for sites with multiple surfaces."
    },
    "task": {
      "type": "string",
      "description": "Plain-English intent, e.g. 'find Apple's latest 10-K'. No URLs — intent, not destination."
    },
    "variants": {
      "type": "object",
      "description": "Optional. Behavior facets when one matters: `{ auth_state: 'logged_in'|'logged_out', role: 'owner'|'admin'|'member'|…, locale: 'en-US', region: 'EU', currency: 'USD' }`. Set `auth_state: 'logged_in'` (with `role` when the privilege matters) to request the SIGNED-IN view of a recipe — the owner-only surface behind login — vs the default logged-out one. The assumed facets come back on `variants_assumed`. Affects cache key — omit when uncertain (you get the logged-out view)."
    },
    "scopeHint": {
      "type": "string",
      "description": "Optional. Only after a prior `ambiguous_scope` — pass one of `error.scope_options[].pattern` verbatim (leading slash, no trailing)."
    }
  },
  "required": [
    "site",
    "task"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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 sin

{
  "type": "object",
  "properties": {
    "envelope_id": {
      "type": "string",
      "format": "uuid",
      "description": "`id` from a `status: ok` envelope. Miss envelopes have no `id`."
    },
    "success": {
      "type": "boolean",
      "description": "True ONLY if the recipe ran clean — every step as written, no retries, no JS-eval fallbacks, no extra clicks. False on ANY deviation, even if the user got the right answer another way."
    },
    "evidence": {
      "type": "object",
      "description": "REQUIRED on every call. Describe how the RECIPE behaved — NOT what you found for the user. `{ what_happened: string, error?: string, screenshot_id? }`. `what_happened` should name which steps ran clean and which needed retries/substitutions/JS-eval/extra clicks. ❌ 'Found restaurant X with 4.9 stars' (task outcome). ✅ 'All 6 steps ran as written' (clean). ✅ 'Steps 1-4 clean. Step 5 `All filters` locator missed; tried 3 selectors then used raw JS click. Step 6 never reached.' (hiccup). Re-crawl reads this to decide what to fix."
    }
  },
  "required": [
    "envelope_id",
    "success",
    "evidence"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Run a deterministic, precompiled recipe on Bowmark's backend and get the result directly — no browser needed on your side. Call this ONLY when an `ask` envelope came back with an `executable` block; the `script_id` comes from there. `inputs` maps each param in the envelope's `executable.param_schema` to a value (e.g. `{ "zip": "94107" }`). Provide every required param. Response is one of: - `{ status: "ok", outputs: {...} }` — `outputs` is the live, freshly-fetched data. Use it directly. - `{ status: "fell_back", reason }` — the script didn't run clean. DROP BACK to the envelope's `ui_procedure` and execute it yourself. A compiled script is an optimization, never the only path. Do NOT call this without a `script_id` from an `executable` block — there is no script to run otherwise.

{
  "type": "object",
  "properties": {
    "script_id": {
      "type": "string",
      "format": "uuid",
      "description": "`executable.script_id` from a `status: ok` envelope. Envelopes without an `executable` block have none."
    },
    "inputs": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Param name → value for every param in `executable.param_schema`."
    }
  },
  "required": [
    "script_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}