Executes the task on the real websites (the search, the price check, the availability lookup, the configurator, the booking flow) and returns what came back. Runs a script you authored against the get_library vocabulary, on the live sites, and returns { ok, result, logs, error, ms }. Call get_library FIRST — it gives the exact function names, argument shapes, and return types; this description is the LANGUAGE + how-to (get_library is just the vocabulary).

THE LANGUAGE — plain async JavaScript: • bowmark is a ready global (no import). Call capabilities off it — await bowmark.<capability>.<method>(...) — always await, they're async. • Individual sites are callable too, at await bowmark.providers.<provider>.<fn>(...). Use one when you specifically want THAT site; otherwise prefer the capability, which fans out across sites and routes around failures. • Real control flow: await, if, loops, array methods (map/filter/sort/slice), and Promise.all for fan-out. • return a value to get it back (JSON-serialized). log(...) for progress lines. • Standard JavaScript built-ins are there (JSON, Math, Date, RegExp, Intl, Promise), plus URL and URLSearchParams — use them to resolve a relative link against the page it came from and to build query strings. Nothing else from the Web platform exists: no fetch, setTimeout, TextEncoder or crypto. • bowmark is the ONLY I/O — no fetch, process, filesystem, or import/require. Write a plain async body, not a wrapping function. • bowmark.files keeps a file the run produces (a CSV, an image, a transcript) in the caller's Bowmark account and gives you a link to it: save({ name, text | base64, contentType? }) → { id, url, expiresAt } (25 MB from a script), list(), get(id), url(id, { expiresIn }), makePublic(id) → { publicUrl }, makePrivate(id), delete(id). Return the link rather than inlining the bytes. • Keep scripts small and deterministic — no infinite loops. Runs in a hard sandbox with CPU + memory + wall-clock limits.

Your own tool-call budget is tighter than you'd guess, and it decides how many calls fit in one script. Most MCP clients time a single tool call out at around 55 seconds, and ONE ordinary capability call already spends 30-55 seconds of that fanning out to live sites — see COMPOSITION below before calling a second capability in the same script.

SENDING IT: pass the script text as run({ script }) — script is the only argument (there is no site argument; the library exposes every capability under bowmark). result is whatever you returned; logs are your log() lines in order; on a throw/timeout ok:false and error is set.

CHECK status BEFORE ok. It is ok | error | partial | needs_user. • partial means the script RAN and result is real and usable, but some of what it called never answered — so the result is narrower than what you asked for. ok is still true; this is not a failure. incomplete.summary says what happened in one sentence, incomplete.failures names each call that threw and what the site said, and incomplete.degraded names each call that answered while reporting its OWN results thin. You MUST say so when you present the result: name what was missed, and do not describe it as complete, exhaustive, or 'all' of anything. A partial you report as whole is a wrong answer, not a slightly smaller right one. • Before you conclude a partial is final, check incomplete.failures[].fixable. fixable: true means YOUR ARGUMENT was rejected, not the site — the error text names what that function actually takes, so re-read it in get_library, fix the argument and run again; that recovers the whole answer. For any other failure re-running usually returns the same thing. • When a fan-out capability (shipping, flights, hotels, cars, etc.) fails on EVERY provider, incomplete.failures[].dropped carries the per-provider breakdown as an array of { provider, fn, reason, detail } — branch on that instead of parsing the prose in .error. • needs_user means a site needs the USER signed in — it is NOT a failure and NOT something you can fix by editing the script. needs lists the sites; meta.handoff.url is a single-use link that expires (meta.handoff.expiresAt). Give the user that URL, say which sites it covers, and WAIT. When they tell you they're done, send the SAME script again unchanged. Do NOT retry before then — it will stop at the same place and cost another run. Do NOT try to log in yourself, ask them for a password, or work around it with a different site. • Logged-in runs need a Bowmark API key on the connection; if you get needs_user saying so, tell the user to add one rather than retrying.

ONE EXIT IP FOR THE WHOLE SCRIPT: await bowmark.egress.pin({ ttlMinutes: 120 }) before your first call, and every call the script makes afterwards leaves from ONE address. Reach for it when a site binds a cart, a token or a sign-in to the address that made the request, and the symptom is being logged out or asked to start over between steps. It is not a dedicated IP: the exit is a shared residential peer, shared: true says so, and the vendor can still replace it without telling us. Pin FIRST — a site you already called keeps the address it used, and the result says pinnedAfterCalls: true when you left it too late. Up to 7 days; anything longer comes back clamped, and the ttlMinutes you get back is the one that was granted.

A DEDICATED IP, IF pin ISN'T ENOUGH: pin is free and shared — a stranger's device, gone in at most 7 days. bowmark.egress.lease is the other product: a static IP nobody else is ever served, ordered for a real term and charged to the account, for a site whose session dies even on a pinned exit. Reach bowmark.egress.quote({ country }) first — it returns your own price for that country's real availability, read live; never assume a term or a number. lease({ country, idempotencyKey }) places the order (idempotencyKey is yours to choose, so a retried call cannot buy two); it is STATIC ISP ONLY today, real money, and there is no refund — confirm with your user before calling it, the way you would before any other purchase. list() and get(id) read what the account already holds; use(id) routes this run's later calls through one specific lease; release(id) stops auto-renewal (the IP keeps working for its already-paid term, then goes away for good).

SAVED SECRETS: savedSecrets lists every secret the run stored in the user's Bowmark account, each as { name, type, viewUrl }. An API key a key-making function returns is saved there automatically as <vendor>_api_key, and later runs that call that vendor use it with nothing to configure. When savedSecrets is present, tell the user what was saved and give them each viewUrl, where they can view or manage it.

trace is the execution trace — every capability you called and the providers it fanned out to under the hood: [{ kind:'capability', capability:'flights', method:'search', ms }, { kind:'provider', capability:'flights', provider:'google_flights', fn:'search', results, status, ms }, …]. The script never visits websites — it calls capabilities that route to providers, and the trace is the receipt.

COMPOSITION MEANS PARALLEL, NOT SEQUENTIAL, AND THAT GOES FOR PROVIDER CALLS TOO — an await inside a for loop is the single slowest thing you can write here. Measured 2026-09-18 over 147 real runs: a script with one awaits a for-loop body ran a median of 49 seconds against 19 for the rest, and on YouTube transcripts specifically, three fetched one after another took 27.3s where six fetched together took 9.8s. Collect the ids first, then Promise.all over them; never walk a list awaiting each item. Default to ONE capability call per script — most already spend 30-55 seconds of your own ~55-second tool-call budget on their own, so a second call made AFTER the first routinely never returns before your client gives up, and the script errors with nothing to show for either call. If you genuinely need several, run them TOGETHER inside Promise.all — in parallel they cost about what one call costs, not the sum of them — and never call them one after another. To sweep a date range, call the search per date inside Promise.all and sort/filter the merged array (each flight result carries its date, so you can tell the runs apart). See the get_library examples for the exact shape. If even one call will not fit your budget, narrow the query (fewer dates, a single site instead of a fan-out) or split the work across separate turns — do not compose more into one script to make it fit. A FAN-OUT OF FIVE THAT LOSES ONE SHOULD STILL HAND BACK FOUR: Promise.all rejects the whole thing the moment any leg does, so one refused request turns a finished answer into nothing. Use Promise.allSettled and keep the fulfilled legs. That is safe HERE and nowhere else, because Bowmark reports the dropped leg for you — the runtime counts what your script CALLED at the dispatch point, not what it chose to report, so a swallowed failure still comes back as status: 'partial' with the call named in incomplete. Say so when you present the result.

SOME capabilities return their rows alongside a warnings array — { flights, warnings }, { hotels, warnings }, { cars, warnings }. Others return a bare array. The signature in get_library tells you which; go by it rather than assuming. Where there IS a warnings array it names any site dropped from the fan-out, and the rows themselves look identical with or without it. Read it, and pass on anything it says rather than quoting a 'cheapest' that only ranks the sites that happened to answer. Dropping warnings from what you return does not hide it — the run comes back status: 'partial' regardless, because the runtime counts what your script CALLED, not what it chose to report.

bowmark.delegate hands a task to a coding agent (Claude Code) in a fresh, throwaway Linux machine — for work that needs a real computer: write and run code, work in a git repo, install packages, process files. It is billed to the account for machine time and model tokens, under maxCostUsd (default $5), so tell your user it is running and that it costs money. start({ prompt, env?, repo? }) returns id at once; pass any token the task needs in env, never in the prompt. In later runs call status(id, { waitMs: 60000 }) until it is idle, then read result, files and diff, and stop(id). send(id, message) continues the same conversation. It is not for reading a website — use the library or browser_agent for that. get_library({ query: "coding agent" }) has full types and examples.

bowmark.browser_agent is a one-shot live browser for ONE task on a site nothing in the library covers (a lookup came back empty, or a function failed on it). It is billed per turn to the account, and it is not a watcher: it cannot poll on a schedule or run unattended, so a standing watch or daily job is not a fit — say so. When it fits and your user asked you to get the thing done, start({ task }); it returns id and watchUrl at once, and in the same reply tell them it is running, that it costs money, and give them watchUrl. A login only they hold does not stop it — they sign in themselves on the live browser through that link. If you hold off for any reason, still NAME it in your reply with its cost — never end on a manual workaround without mentioning it. In later runs call status(id, { waitMs: 60000 }). When status is needs_input, relay question to your user and send(id, their_answer). When idle, read result and stop(id). Always stop a session when done — idle browsers keep spending money. Your account holds max 3 concurrent sessions. One task = one goal: never bundle multiple queries into one task or the agent silently reuses results. Start separate sessions for each. A NORMAL task takes 1-4 poll cycles to reach idle — roughly 1-3 minutes total, not one. Each poll's steps shows the agent's current activity, and the SAME step name on back-to-back polls (or a run of DIFFERENT step names) is ordinary mid-task activity, not a stall — do not stop a run that is still inside that window just because progress looks repetitive. get_library({ query: "browser agent" }) has full types and examples.