Changelog

Browser fetch: a page's own data, with no model (October 2026)

• POST /v1/users/{user_id}/browser/fetch opens one page in a background tab of the user's own browser, with its sign-ins, works your steps (click, type, scroll, wait_for, page_fetch) and answers with the bodies of the page's own data calls that match capture. No model runs.
• Only sites in the deployment's browser.allowed_domains open (403 domain_not_allowed), and never a page on its browser.blocked_paths, such as a payment page (403 page_blocked, which leaves a browser.page_blocked row in GET /v1/audit-log: the host and path, never the query).
• keep_open_ms keeps the tab, named by tab, for the next fetch, which sends no url. front: true opens it in front of the person's window instead, as a phone (its size, user agent and touch), for a sign-in they finish themselves; other fetches run behind it, a session's screen carries its crop, and neither the browser watch nor the screenshot (409 browser_in_use) ever shows its page. Four run at once (409 browser_busy), a person using the browser comes first (409 browser_in_use), and a slow page is 504 timeout with what came in partial.
• GET /v1/users/{user_id}/browser/watch streams the fetch's tabs live, read only; it never wakes the computer. A fetch's tag names its tab there.
• An optional click takes within_ms (up to 10000): it looks that long for an element that shows a moment after the page, such as a site's popup, then goes on without it.
• A click takes nth (which match, from 1) and near_text (the first match after a text, or after texts in turn).
• stage: true: in front, one kept tab, alone in the watch.
• private: true: a fetch the browser watch never shows.
• front_device: "desktop": a hand-off on the site's desktop page, as the other fetches see it.
• challenge: "turnstile": the page called Cloudflare's Turnstile check.
• GET /v1/users/{user_id}/browser/cookies?domain=&names=: which cookies of those names the browser holds for an allowed site, and until when. Names and expiry only, never a value; it opens no page, so read it every few seconds to see a person finish signing in on a front page.
• A session that only watches (screen: "view") shows nothing while its screen is private: a person signs in on that computer (a front fetch, from its start until its tab closes), or a private fetch runs or keeps its tab (a later fetch on that tab counts too). GET /v1/sessions/{session_id} answers screen_paused: true, GET /v1/sessions/{session_id}/screen answers 409 browser_in_use, and the screen page hangs up and says the screen is private right now, then comes back by itself. GET /v1/users/{user_id}/screenshot answers 409 browser_in_use then too. A control session, the person's own, is unchanged.
• front_crop (role, name or text): a hand-off's screen shows only that element of its page, such as a site's sign-in dialog, at a phone's size. From a front fetch's start until the element is on the page, GET /v1/sessions/{session_id}/screen answers crop_pending: true and the screen page shows no picture yet; after 20 seconds without it, the page's part shows as before. The screen page also asks again while the computer is still waking (browser_not_open), for up to 30 seconds.
• A session's screen page checks every 3 seconds whether the session is still open. When your server ends it (DELETE /v1/sessions/{session_id}), the page says it can be closed, tells the page around it (vestra:ended; embed.js fires vestra-ended), tells a window that opened it the same, and closes its own window when a script opened it (a frame never closes itself). A screen opened before its hand-off takes the hand-off's crop as soon as it comes.
• POST /v1/sessions takes driver with screen: "control": user opens the screen in your user's hands from the first frame the page shows, with no Take control and nothing to give back, for a page that is theirs to use (a sign-in Bash opened for them). bash, or none, is as before: they watch first and tap Take control. driver: "user" with any other screen is 400.
• A front_device: "desktop" hand-off now runs at a phone's shape, 440 wide and as high as the window, still with the site's desktop page: a sign-in service's tab it opens draws into the same part of the screen, so a session's screen shows one rectangle whatever is in front. On a hand-off's page (a crop) the screen page has no bar: the person's first tap on the page takes control and opens the keyboard.

What approvals enforces, said plainly (October 2026)

• approvals lists what Bash asks the person before doing. The manifest and file references, the guides and the agent skill said it lists what "always waits for the person's yes", which only a system approval makes true, and not every path has one yet. A system approval enforces what approvals lists for your own functions and your MCP servers' tools that wait for a yes; in a browser or a connected app, Bash is instructed to ask.
• Nothing changes in how Bash behaves: the docs now say what it does. When a system approval covers every path, this changelog says so.

Bash's own names are reserved (October 2026)

/v1 is not public yet, so this changes the contract on purpose.

• A function tool named like one of Bash's own tools (execute_code, mcp_invoke, github_pull_request and the rest of the box's catalog) is refused with 400 tool_name_reserved when a version is saved (a file or a manifest) or a message brings it. Bash skipped such a function before, keeping its own tool, so the call you meant never happened. The check is exact: only Bash's own names, never a pattern. The names are reserved whether or not a deployment uses that capability: remember is refused even for a company whose memory is off, and a tool behind a feature not yet on for you is reserved all the same, so turning it on never breaks a saved version.
• An MCP server's slug can't be one of Bash's own tool servers (composio, browser-control, os-hands, vestra): POST /v1/mcp-servers refuses it with 400 tool_name_reserved on slug, a file never registers one, and a new version naming a server made before this (directly, or by its URL in a file) is refused the same way. Register the server again under another slug and point your next version at it (a file then uses the new one); don't delete the old one while a live version still runs it.
• Nothing already saved changes: a version saved before this keeps running, Bash's own tool answering to the name. Only a new version, a new server or a new message is checked.

A limit's stop is a stop (October 2026)

/v1 is not public yet, so this changes the contract on purpose.

• Work that a limit or a policy stopped now ends with task.stopped, as the conversation's own record already said, and says why in two new fields: reason, one of max_turns (it used every turn it had), max_budget (it reached a budget cap), credits_exhausted (the account's credits ran out) or hook_blocked (a policy hook in your company's rules stopped it), and message, more about why in plain words (for hook_blocked, the hook's own words; null when there is no more). The first two used to arrive as task.failed with that reason and message: null.
• Credits running out has its own reason, credits_exhausted, on task.stopped, whether the account was out of credits before the work started or ran out while it ran. It used to arrive as task.failed with max_budget (or credits_exhausted), or as a stop with no reason; max_budget now means only a budget cap (a task's limit, a turn's spend ceiling, or the day's budget).
• A stop by you or a person carries neither field, exactly as before. Wait on task.stopped or task.failed as you already do: only the event a limit's stop arrives as has moved.
• Both SDKs type the two fields on task.stopped (optional), and the events reference lists them. The CLI's event lines and init's interview say why a stopped work stopped when the event says.

The one yes shows the price (October 2026)

• vestra init now gives a function that waits for your customer's yes each value the customer agrees to as an input, so its approval shows them: a bike rental's extend_rental takes rental_id, charge_usd and new_due_back. With rental_id alone, its approval read "charges its daily_price_usd" with no number. Init asks what the customer agrees to and where Bash finds it, declares those values as required inputs named and written like your example results, and writes instructions that say where each comes from ("call extend_rental with charge_usd set to daily_price_usd from get_rental"). When no lookup returns a value (your code works the price out as it acts), init asks for one that does, such as a quote, and declares it read_only: Bash never guesses a value for the approval.
• Your code checks those values against its own before it acts, and throws when one differs, so nothing is charged that the customer did not see. Init's closing words say so for each such function, naming its inputs, and for one whose approval shows only what it acts on, they say to add the values the customer should see. A function you declared before keeps its inputs: add the values yourself, and the check in your code.
• A company action's summary (at most 120 characters) never cuts an argument any more. Short of room, it leaves out the description's first sentence, then each argument that does not fit, and ends and N more: extend_rental: rental_id R-1042, charge_usd 15, new_due_back 2026-10-05 18:00 where it used to read ... extend_rental: rental_id R-1042, charge_us…. details.rows is unchanged: the call's first 8 arguments, each value up to 200 characters.
• The tests vestra init and vestra test --generate draft check what the approval shows (The approval shows the charge of 12 and the new return time 2026-10-07 17:30.), never what Bash says before it: Bash may go from its lookup straight to the approval. The starter test of the customer's no is kept once drafted, whatever a check of its wording finds.

A test never makes a routine (October 2026)

• In a test run, a routine the test customer asks for is never made: Bash answers as it would for a real one, with when it would run, but nothing is scheduled and nothing runs later. Asked for their routines, the test customer sees only the ones made in that test, never another test's or an earlier run's. Your real customers' routines are unchanged.

Your functions wait for a yes (October 2026)

• A function your code answers (tools: with function:, or a tool an ask declares) now waits for the customer's yes before its call reaches your code, as every tool of your MCP servers already does. Two new fields let one run at once: read_only: true for a tool that changes nothing (a lookup), and run_without_asking: true for one that changes something that needs no yes. Both are optional and default to false; setting both is fine. The SDKs' tool() takes them too.
• Mark your lookups read_only: true. Every version saved before this change marks none, so each of its functions, lookups included, now waits for a yes: there is no shim. vestra init marks the lookups of a new file for you. In a file you already have, add the line yourself under each lookup, such as get_booking: read_only: true, then vestra deploy.
• The wait is a real approval: interaction.created of type approval, whose summary says what will happen, from the first sentence of the tool's description, then names the tool and each argument (Extends a rental by one more day. extend_rental: rental_id R-1042, at most 120 characters), and whose details carry tool_name and the arguments as rows. A company MCP tool's approval reads the same way: its summary used to be the description alone, lowercased, with two arguments; it now leads with the description as written, then <tool>: <every argument>. On a yes your code gets the usual tool_call; on a no the function never runs, and Bash is told the customer declined.
• In a conversation, Bash starts work to call a function that waits, and the work asks first. A function marked either way is still called at once. A routine, a batch or an ask with no person in your app has nobody to say yes, so a function it calls waits until the approval expires: mark one that may run there run_without_asking: true.
• The yes to a company action (a tool of your MCP servers, or a function of yours that is not read-only or run without asking) needs present_user: true, sent for the person who saw it, as a payment's does: without it, 400 present_user_required. A no never needs it.
• In a test, the test customer says no to a function's approval, unless the test sets approves: true; then its tool_results entry answers the call, by the function's name.
• moves_money on a company action's card (a function of yours, or a tool of your MCP servers) is null, meaning unknown: your app knows what your tools cost, so show the price your own way. It used to say false, even for a function that charges. The field is now boolean | null in the contract and both SDKs; every other card is unchanged.

init round-trips (October 2026)

• GET /v1/deployments/{id}?format=yaml, and the tests vestra test --generate adds to your file, quote any word a YAML 1.1 reader would read as another type: a time such as "10:15" (YAML 1.1's base-60 number 615), "yes", "010", "1_000", a date. Deploying the file vestra init wrote is "nothing changed" from every SDK and the CLI. A key named on, such as the routine's own on: call, stays as it is.
• The Python SDK reads vestra.yaml by YAML 1.2's rules, as the TypeScript SDK and the CLI do. In a file you wrote by hand:
  • A time (10:15) and a date stay words, and 010 is ten.
  • 1_000 and 0b101 are words; 1e3, 6E10, +.5 and 0o17 are numbers.
  • Only true and false are booleans (yes, on and off are words, as before).
  • A << key no longer merges another mapping: it is a key like any other.
• A file you deployed through the Python SDK 0.1.3 with an unquoted time from 10:00 on went up with that time as a number. Your next deploy sends it as written, so it makes one new version.
• A reply in a deployment interview (POST /v1/conversations/{id}/messages) goes straight to the interview's work, which asks its next questions in its turn-ending words or through a question interaction. init in each SDK also shows a question the interview asks in its own reply, so it never waits on words already said.

One card, train 8a (October 2026)

/v1 is not public yet, so these changes break the contract on purpose: old routes and event names are removed, not aliased.

Whose Bash

• Every request that acts on a Bash takes user_id, your id for the person (1 to 128 characters, starting with a letter or digit). The first request that names a user creates them, and sends user.created.
• No user_id means your company's own Bash: one per company and mode, with the company's memory mode. It is never named in a view: a conversation, task, file, interaction or event on it shows user_id: null.
• PATCH /v1/org takes require_user: true to refuse a request without user_id (400 user_required).
• A batch item with no user runs on the company's own Bash, at most 5 at a time per company.

ask

POST /v1/conversations and POST /v1/conversations/{id}/messages take stream: true: the answer is that turn's events as text/event-stream (201 for a create), ending when the turn completes, fails, stops or waits on you. A retried request with the same Idempotency-Key gets the stored JSON instead; resume with GET /v1/conversations/{id}/events and Last-Event-ID.

answer

An answer's body fits the item's type: an approval takes { "approve": true } or { "approve": false } (with present_user, message, nonce), a question { "answers": [...] } or { "approve": false }, a connection { "approve": false }, a hand-off { "done": true }, { "could_not": true } or { "not_now": true } (or { "answers": [...] } when it asks for a value, such as a code), a client tool call { "output": ... } or { "error": "..." }. Any other body is 400 answer_mismatch, naming the shapes that fit. The answer is { id, object: "interaction", type, status }. An interaction's type can be tool_call, and its task_id is null when Bash made the call while replying, outside any piece of work.

Events

One catalog names every event, on the stream and in webhooks.

• Every turn change is a conversation.status on the stream, with turn_id and turn_status (running, working, requires_action, completed, failed, stopped). A turn that settles (completed, failed, stopped or requires_action) also sends it as a webhook, with the turn's data, outcome, error and usage. Its usage.cost_complete is true when every charge of the turn and its work was in as it settled; when false, the rest arrives on usage.updated and the task endings.
• An answered client tool call sends interaction.resolved; one that timed out sends interaction.expired. Expiry events come for tool calls only, for now: other waits end in interaction.resolved.
• Stored stream events, the event log and your webhook endpoints' event filters were moved to the new names. Events already sent keep the data they were sent with.

One card, train 8b (October 2026)

Like train 8a, these changes break the contract on purpose: old routes are removed, not aliased.

Sessions (watch, talk, embed)

• POST /v1/sessions answers { id: "ses_…", token, url, frame_ancestors, expires_at, … }, and creates the user the first time it sees the id. The token lives 15 minutes and reaches only that user and the session's conversation, and never shows money; anywhere else it answers 404, and it lists no interactions.
• allowed_embed_origins decides only which of your pages may frame a session. With none, a session still opens: its page frames nowhere, and its url works as a page of its own. A call (POST /v1/sessions/{id}/voice) is taken from Vestra's own page and from your allowed origins.
• The memory panel (memory: true) needs PATCH /v1/org { "memory_panel": true }.
• The ids emb_, bs_ and vs_ are gone; ses_ is new.
• session.ended carries session_id instead of voice_session_id, and is also sent when a session is revoked (end_reason: "revoked").

Flat paths

user_id moves into the body or the query. Leaving it out means your company's own Bash (for secrets, your company's store); the company-wide lists show everyone without it, and an unknown user_id on a read is 404.

• GET /v1/files?conversation_id= lists the outputs of that conversation's tasks. Every file names its conversation_id.
• GET /v1/events takes after=evt_… to read forward, oldest first.

Routines

ask replaces message; every takes plain words (weekday at 08:00), read in the user's time zone; on: "call" answers a trigger_url; name is optional. routine.fired now also rides the conversation's stream. Bash can make, list and pause routines when a user asks.

Keys

Keys carry scopes (all, or any of runtime, setup, admin); a key without the scope a route needs answers 403 scope_missing, and a key gives only the scopes it has. Erasing or exporting a user needs admin. GET /v1/me answers every key, whatever its scopes.

Also

Conversation.last_event_seq is new. Idempotency-Key is listed only where it is honoured, and honoured everywhere it is listed.

One card, train 9 (October 2026)

/v1 is still not public, so this train changes the contract where the card needs it.

deploy: the file

• vestra.yaml declares a deployment whole: instructions, language, model, apps, tools (MCP servers by URL, and function tools your code answers), skills, knowledge, approvals, memory, the computer, routines, limits, tests and webhooks. Its JSON Schema, for editors, is https://vestra.ai/developers/vestra.schema.json (openapi/vestra.schema.json in the repo).
• PUT /v1/deployments/{name} applies it, sent as JSON. The first call makes the deployment (201). A file that means what the latest version's file means makes no version and answers changed: []; otherwise it saves a version and names the fields that changed. The answer is always { object: "deployment_apply", deployment, version, changed, tests, promote, new_webhooks }, and new_webhooks shows each new endpoint's signing secret once.
  • Until tool policy is stored per version, an MCP server's tool policy is one setting shared by both modes, so a live key's change takes effect when the file is applied, not when the version is promoted.
• ?promote=after_tests (the default) runs the version's tests and promotes it in the key's mode when they pass: a test key moves the draft, a live key moves live. now promotes at once. no promotes nothing, but it is not a dry run: when the key's mode already runs the version (the same file again, or a new deployment's version 1 with a test key), the webhooks and routines the file declares are still made to match it, as on every apply. The events are test_run.completed, then deployment.promoted, which a test key's promotion now sends too.
• A file naming a company secret the key's mode does not hold answers 400 secret_missing with error.names: store them with PUT /v1/secrets/{name} and apply again. A refused apply writes nothing.
• MCP servers are registered by URL and reused: a server with the file's URL is made to match the file. A server's headers and tool settings are the same for every deployment and mode that names it, so when it runs elsewhere with other settings (another deployment's live, draft or newest version, or, for a test key, this deployment's live version), the apply answers 409 mcp_server_shared with error.deployments and writes nothing; a server only this deployment runs can be changed with a live key. A display name alone is never a difference, and an archived deployment holds no server. Give a deployment whose tool settings differ its own server, at another URL.
• A function tool named like one of Bash's own tools, or whose input is not an object, is refused when a version is saved (400 tool_name_reserved, 400 tool_schema_invalid), in a file or in a manifest, instead of failing every ask afterwards.
• Tests become the deployment's scenarios. Routines and webhooks the file declares belong to it: an apply that drops one removes it, and nothing made by hand is touched. A routine for: us runs on your company's own Bash. A routine for: each customer is a template: each customer gets their own copy the first time they talk to Bash on this deployment, never all at once, and removing it from the file stops every copy. Copies count toward your company's 200 active routines in each mode; a customer past that gets no copy.
• GET /v1/deployments/{name}?format=yaml answers the latest version as vestra.yaml, an interview's draft included.

Webhooks and skills

• A webhook endpoint shows deployment_id and managed_by. An endpoint a file declares hears its deployment's events and your company's account events only.
• A company skill shows sha256, the hash of its files as uploaded, computed the way the SDKs compute a folder's, so an unchanged folder is never uploaded again.

One card, train 8c (October 2026)

Nothing in the contract is removed or renamed. Three things now hold on a bad day.

• A test run whose server stopped now ends. A run that stops reporting for 15 minutes (a deploy or a crash cut it off) ends as status: error with error_code: interrupted, and sends its test_run.completed. It promotes nothing: apply the file again (an unchanged file runs its tests again) or start the run again. test_run.completed now carries error_code, which is null unless the status is error.
• A reply cut off on our side fails fast. A turn whose server stops fails with process_lost about a second after a deploy replaces the server, and within two minutes when a server stops without warning, instead of after 10 minutes. The conversation takes your next message at once.
• A database stall no longer loses a reply. An event the server could not write is tried again, and is still written exactly once, its webhook included.

One card, tool policy per version (October 2026)

• An MCP server's deny and require_approval in vestra.yaml now belong to the version the file makes, not to the server. A file's policy changes only its own version, and takes effect when that version is promoted in a mode: a test key's promotion moves the draft, a live key's moves live. Two deployments on one MCP server keep two policies. A version shows it as manifest.mcp_tool_policy, by server id, and POST /v1/deployments/{name}/versions takes it too.
• The tool policy on the server itself (the tools of POST and PATCH /v1/mcp-servers) is now a floor. Every deployment, in both modes, runs under it, and a version's own policy adds to it and never removes from it: a tool denied by either never runs, and a tool either one asks about waits for the person, unless one of them denies it.
• A file no longer writes a server's tool policy. A server a file registers starts with an empty floor. A server a file registered before this change keeps the policy that file gave it, now as its floor, until you change it with PATCH /v1/mcp-servers/{id}.
• 409 mcp_server_shared is now about headers only: a different tool policy on one URL is never a conflict.
• A test key can no longer change an MCP server that a deployment's live version uses: PATCH /v1/mcp-servers/{id} that changes its URL, auth or floor, and DELETE, answer 409 mcp_server_live. Change it with a live key, or as an owner or admin. A new name alone is not a change.
• The first apply of an unchanged file after this change saves one new version when the file gives any MCP server a policy: that version carries the policy. Versions saved before this change carry none of their own and run under the server's, as before.
• A version with no policy of its own shows the server's floor in its file. Edit and apply that file, and the floor's lists become that new version's own: loosening the floor later does not loosen them.

One card, the doors and the developer site (October 2026)

Nothing in the routes is removed or renamed.

• /v1/mcp offers two more tools: init, which runs the setup interview a reply at a time and needs a test key, and test, which runs a deployment's scenarios and waits up to 45 seconds for the verdict. It never deploys: in your editor, vestra mcp offers deploy from your own computer.
• The TypeScript and Python SDKs and the CLI gain init, deploy and test, so vestra.yaml is written, applied and tested from every door. The CLI's vestra dev deploys every save to test mode while you build.
• The developer site, /developers, has a page for each line of the card, with its routes from the contract and a sample from each door, every one checked in CI. The API reference moved to /developers/reference.
• A usage line item for Bash's own replies says Reply by Bash, no longer Orchestrator reply, and a refund keeps Bash's name (Refund: work by Bash). These words are for people: branch on category, which is unchanged.
• A test's judge counts an approval Bash asked for, which the test customer declined, as a broken rule only when a never line forbids offering or attempting that action; otherwise it is asking first, whatever raised the ask (approvals.always, an MCP server's require_approval, a browser action). Tests drafted by vestra init and vestra test --generate for a setup whose instructions forbid an action carry the never line "Offers, attempts or claims to" that action, so a Bash that offers it fails, even when the test customer said no. A test written before keeps its verdict unless its own never line forbids the offer.

One card, a company action asks first (October 2026)

• Every tool of your MCP servers now waits for your customer's yes before it runs, in live and test mode alike, unless your server marks it read-only (MCP readOnlyHint: true) or your file lets it run without asking. Before, a tool asked only when require_approval listed it. Bash takes the read-only mark on your server's word, so mark only tools that change nothing.
• run_without_asking in an MCP server of vestra.yaml lists the tools that run without the yes. A version shows it in manifest.mcp_tool_policy, beside deny and require_approval. A tool goes in one of the three lists at most (400 tool_listed_twice), and a name your server does not list is refused when you apply the file (400 tool_not_on_server, naming it and the tools the server lists).
• require_approval still asks, even before a tool your server marks read-only, and deny still wins over everything.
• The approval your customer sees takes its words from your server: the tool's description, and whether it may remove or undo something (destructiveHint; left out, it may). Its rows are the call's own arguments. The approval your app receives names the tool itself and its server in details, not mcp_invoke.
• approvals in your file still lists what Bash asks about on its own. For bookings and cancellations, Bash now also says the system enforces them when they are done with your MCP servers, and only while your file lets none of their tools run without asking. A tool you declare under tools: runs your own code, so the system makes no such claim for it.
• vestra init says which tools will ask and offers to let some run without asking, and drafted tests expect Bash to ask before a tool that changes something.

A test never really changes anything (October 2026)

• In a test run, a tool of your MCP servers that your server does not mark read-only never runs on your server, even one your file lets run without asking. Your test's tool_results entry for it, keyed <server>.<tool> (the server's slug, then the name your server lists the tool under), plays its answer; with none, it does not run, and Bash carries on.
• The transcript says which: "Bash called cancel on your MCP server mcp-tripnest-example; in a test it did not run there, and the test's fixture answered: ...", or "In a test, Bash doesn't run cancel on your server. Add a tool_results entry for mcp-tripnest-example.cancel to play its answer." The judge reads it: the call not running is never Bash's failure, but whether Bash should have made the call at all is still judged by your never lines.
• tool_results takes <server>.<tool> keys when the version has an MCP server; a key without a dot still has to name a tool you declare (400 tool_not_declared). The test's interaction.created for such a call names its server: it is the test's to answer, so your app ignores it.
• Drafted tests give tool_results for the tools your file lets run without asking. A read-only tool runs in a test as it does live, and a plain test-key ask (not a test run) still calls your server.