Bowmark

Get a sign-in link for one site, so the user can sign Bowmark in to it right now, before any run needs it. Pass the site as a domain (`youtube.com`), a URL, or a provider id. **Call this whenever the user asks to log in, sign in, connect or link an account on a site** — never send them to the Bowmark Link extension or the dashboard to do it themselves. It returns `url`, a single-use link that expires (`expiresAt`). Give the user that URL and say which site it is for. On that page they sign in with Bowmark's own browser, or, in desktop Chrome with Bowmark Link installed, press "Use Chrome extension" to send the login that Chrome already holds. When they say they are done, `list_connections` shows the new login and every later run uses it. When Bowmark cannot sign in to that site, it says so and returns `sites`, the sites it can sign in to. Tell the user plainly. Do not offer a workaround that asks for their password. A public page on that site still works without a login: `get_library` shows what can read it. To sign back in to a saved login that stopped working, pass its `id` from `list_connections` as `connection`. The fresh session goes into the SAME id.

Start deleting a saved login by the `id` `list_connections` returned. **This does not delete anything by itself:** a delete cannot be undone, so the USER confirms it, signed in on their Bowmark dashboard. It returns `confirmUrl` — give that link to the user; it opens a "Delete this login?" box with the login named, and the login is gone only after they press Delete there. Nothing you can call completes it for them. Only call this when the user asked to remove a saved login. To sign out of a site, use `logout_connection` instead. Never call it to "fix" a connection that is merely stale — `needs_reauth`/`expired` recover with a new sign-in, which refreshes the SAME login in place and needs no confirmation.

**Use this whenever a task touches a live website.** It answers, definitively and cheaply, whether Bowmark can already DO the thing: current prices, real availability or stock, a site search, a quote or a fare, a configurator, a booking, anything behind a form or a filter. **Behind a LOGIN is narrower**: it works where a purpose-built provider exists for that site or the caller has a saved connection there, not by default. **Use this for Bowmark questions too.** Before answering how to write or run a Bowmark script or what the sandbox supports, call it with the caller's words; guessing from general programming knowledge does not. **Checking is cheap, so check.** One read-only call, no site is touched, and a query that matches nothing returns a one-line index instead of an error. If nothing fits, you have lost one cheap call and can use your normal approach. Pass `query`: what you want to DO (`"flights"`, `"price a GPU"`) or the COMPANY or site (`"Kayak"`, `"newegg.com"`). If the caller gave only a URL, use its hostname as the query. Naming a host is worth it even when you expect nothing, because Bowmark also reads that site's OWN published tools, live. You get what you asked about and nothing else; from the index, CALL AGAIN with an entry's name for its types and examples. Several parts? Pass `queries: ["amazon", "youtube"]`, one per part, in ONE call. **Read the first lines of the answer.** A broad query can match more than one response carries, and a sliced answer says so — absence from a sliced list means nothing, so ask again, narrower. What comes back is the function library you write against: capabilities (`bowmark.flights.search(...)`), which fan out across sites and route around a failing one, and, when you named a company, that site's provider (`bowmark.providers.kayak.search(...)`). Prefer the capability. Loop: call `get_library` → write a JS script against the `bowmark` global → send it to `run`. The full reference is `get_library({ query: "run guide" })`.

Return the dashboard link for one stored secret this account holds, so you can answer "where is my Acme password?" with somewhere to go. **It returns a URL, never a value** — opening it requires the user to be signed in and to confirm who they are, and only their own browser can read what comes back.

List the saved logins this account already holds, one entry per login: its `id` (name it in a signed-in call as `{ connection: id }`), the site, which account on that site, whether it works right now (`usable`), and when it was made, last used and last checked. **Call this before any task that needs a login, and again whenever you come back to one later.** A `usable` login means the site is already signed in: do not ask the user to sign in, just run the script, naming the id if the site has more than one. Prefer the login you used before over a new one. A login marked `needs_reauth`, `expired` or `logged_out` is not lost. Run the script anyway (name the id if you know it): it pauses with a link, and signing in through that link puts the fresh session back into the SAME id, so you can keep using it. To add a login for a site with none, call `add_connection` — it hands you a sign-in link for the user. `delete_connection` only asks the user to delete one this account already holds.

List the stored secrets this account holds, by NAME. Returns name, type, which hosts each may be used against, when it expires and when it was last used — never a value, and no Bowmark endpoint returns one. **Call this BEFORE `request_secret`.** A secret the user has already set is ready to use; asking for it again sends them to a page for nothing. In a script, refer to one by name: `bowmark.secret('acme_pw')`.

Sign a saved login out by the `id` `list_connections` returned. Bowmark drops the cookies it held, and where the site supports it (`siteLogout: "supported"` in the reply) the session is ended ON THE SITE too — `siteSignedOut: true` means Bowmark checked the site no longer accepts it. The saved login is KEPT, status `logged_out`, so the user can sign back in to the same entry later. Call this when the user asks to sign out of a site. `delete_connection` is the other action: it hands the user a link to forget the entry entirely, which leaves the site session alive.

Record what was missing, wrong, or incomplete so Bowmark can build it. Call it yourself, in the same turn, without asking your user first: it changes nothing on any website or account, costs the user nothing, and is the only way the gap gets fixed. Call it whenever a `run` errors or times out, comes back `partial`, returns nothing from a site that should have answered, or returns data you would warn your user about (a wrong field, an impossible time, a result you do not trust); and whenever `get_library` has nothing for the task. Pass the `runId` returned by `run` when this report is about a run; omit it when `get_library` did not cover the task. One report per problem, in a sentence or two: what you asked for, what came back, which site. This records feedback only and does not retry a run. For an account holder the result may also carry `supportRoom`, a live chat with Bowmark support about this report: follow the instructions that come with it. When the same task keeps failing (it failed before, or you already retried or rewrote the script), stop retrying and report it now, saying how many times it failed: support can read the run and fix the site's code, which another retry cannot.

Create a named, empty slot for a secret and get back a link the user opens to fill it in. They type the value on a Bowmark page and choose how long it lives, from 5 minutes to never. It is encrypted in their own browser before it leaves, so nothing on the way — this connection included — ever sees it. **Give the user the link. Never ask them to type a password, API key or one-time code to you.** A secret in this conversation is in your context, in the transcript and in the logs. **Name it for the person, not for your script.** The name you pass is the heading on the page they open and the row they see in their secret list months later, so make it `<site>_<what it is>`: `letterboxd_password`, `stripe_api_key`, `acme_totp_seed`. A run id, a timestamp, a uuid or a bare `password` is refused. Call `list_secrets` first: if the name already exists and is set, use it instead. `name` is lowercase letters, digits, `_`, `.` and `-`. `hosts` narrows where the value may be used and is worth passing — a secret is refused against any other site.

**Executes the task on the real websites** and returns the result. Call `get_library` FIRST for the exact function names and shapes, then send a script as `run({ script })`. THE SCRIPT is a plain async JavaScript body, not a wrapping function. `bowmark` is a ready global: `await bowmark.<capability>.<fn>(...)`, or one site via `await bowmark.providers.<provider>.<fn>(...)`. `return` what you want back; `log(...)` for progress. Built-ins plus `URL`/`URLSearchParams` exist; `fetch`, `import`, `setTimeout` and a filesystem do not — `bowmark` is the only I/O. MIND THE CLOCK. Your client times a tool call out at around 55 seconds, and one capability call already spends 30-55 seconds, so default to ONE per script. Need several? Run them together in `Promise.allSettled` (a dropped leg still comes back as `partial`), never one after another, and never `await` inside a `for` loop. Keep the result under ~25,000 characters. CHECK `status` BEFORE `ok` — `ok` | `error` | `partial` | `needs_user` | `running`: • `running`: it is still going. Call `run({ runId })` to wait for the SAME run; never resend the script. • `partial`: `result` is real but narrower than asked; `incomplete` names what did not answer. Tell your user — never call it complete. `incomplete.failures[].fixable: true` means your argument was wrong: fix it and rerun. • `needs_user`: a site needs your user signed in. It is not a failure: give them `meta.handoff.url`, say which sites, and wait. When they are done, send the SAME script unchanged. • `error`: there is no result; `error` says why. Saving files, one exit IP, saved secrets, `warnings`, `emptyHanded`, and the billed `browser_agent`/`delegate` fallbacks: `get_library({ query: "run guide" })`.

Used by the inline run view to draw a run's progress. You do not need to call this — `run` returns the result.