Events
One catalog names every event. A conversation's stream carries what happens as it happens; your webhooks get what settles. Each event says where it arrives, what it means, and every field of its data.
How each arrives
The SDKs hand you both as one event: event.type, event.user and event.data.
On the stream
seqintegerIts place on the conversation's stream, counting up: send the last one you saw to pick up after it.
- Type
integer
typestringWhat happened, from the one catalog of events: the events reference says what each carries and where it is delivered.
- Limits
- One of 34 values.
- Example
message.completed
datamap of anyWhat it says: its fields depend on its type, as the events reference lists them.
- Type
map of any
created_atstringWhen it happened, as an ISO 8601 time.
- Type
string
In a webhook
idstringThe event (evt_...): the same on every retry, so use it to skip one you already took.
- Example
evt_4hq
object"event"Always event.
- Type
"event"
typestringAn event a webhook carries: every event of the catalog but the six that ride only the stream (message.delta, task.progress, usage.updated, screen.control, error and ping).
- Limits
- One of 28 values.
- Example
task.completed
mode"live" | "test"The mode it happened in: test or live.
- Type
"live" | "test"
created_atstringWhen it happened, as an ISO 8601 time.
- Type
string
user_idstring | nullYour id for the user it concerns; null for your company's own Bash, or when it concerns no user.
- Type
string | null
task_idstring | nullThe task it concerns (task_...); null when none.
- Type
string | null
conversation_idstring | nullThe conversation it concerns (conv_...); null when none.
- Type
string | null
datamap of anyWhat it says: its fields depend on its type, as the events reference lists them.
- Type
map of any
The reply
message.deltastream onlyThe reply as it is written, a piece at a time.
textstringThe next piece of the reply, as it is written.
- Type
string
turn_idstringmay be absentThe turn it belongs to (turn_...).
- Type
string
task_idstringmay be absentFor words a task writes, rather than Bash's reply: the task (task_...).
- Type
string
message.completedstream and webhookThe reply is complete: its answer (its final words, after any search), its whole text, and what the turn cost. An empty text means the turn only started work: task.started names it.
textstringThe whole reply. For a message sent straight to work: Started work on it. Empty when Bash started work without a word.
- Type
string
answerstring | nullmay be absentThe reply's answer: its final words, the part after any search or lookup Bash made on the way, trimmed; null when it said nothing. Absent from older events.
- Type
string | null
turn_idstringmay be absentThe turn (turn_...).
- Type
string
task_idstringmay be absentFor a task's words (every step's, joined), rather than Bash's reply: the task (task_...).
- Type
string
dataunknownmay be absentThe data you asked for with output_schema, when the reply carries it.
- Type
unknown
error{ code: string; message: string }may be absentWhy the turn failed, as a code and a message in plain words; absent when it did not.
- Type
{ code: string; message: string }
usage{ turn_cost_usd: number; conversation_total_usd: number; cost_complete: boolean } | nullmay be absentWhat the turn has cost (turn_cost_usd), the conversation's total, and whether every charge is in (cost_complete); null when it could not be read.
- Type
{ turn_cost_usd: number; conversation_total_usd: number; cost_complete: boolean } | null
The work
task.startedstream and webhookBash started work on its computer: the task's id and title.
task_idstringThe task Bash started (task_...).
- Type
string
titlestring | nullWhat the work is, in a few words; null until Bash names it.
- Type
string | null
turn_idstringmay be absentThe turn that started it (turn_...).
- Type
string
task.progressstream onlyA step of the work, or a change in its status.
progress'step' | 'status'step: a step of the work (a tool used, or its to-do list). status: where the work is (working, waiting).
- Type
'step' | 'status'
task_idstringmay be absentThe task (task_...), on a conversation's stream.
- Type
string
turn_idstringmay be absentThe turn (turn_...), when Bash's reply took the step.
- Type
string
statusstringmay be absentFor a status: working, or waiting on an approval or a question.
- Type
string
toolstringmay be absentFor a step Bash's reply took: the tool it used.
- Type
string
todos{ content: string; status: string; }[]may be absentFor a to-do list: each step of the plan, with its content and its status (pending, in_progress, completed).
- Type
{ content: string; status: string; }[]
task.completedstream and webhookThe work is done: its answer (its final reply), its summary, and what it cost.
task_idstringThe task (task_...).
- Type
string
statusstringmay be absentHow it ended, on the conversation's stream: completed, failed or stopped.
- Type
string
cost_usdnumber | nullmay be absentWhat it cost, in billed US dollars; null when not known yet.
- Type
number | null
cost_completebooleanmay be absentWhether every charge is in: false when the last ones can still land, on usage.updated.
- Type
boolean
summarystring | nullmay be absentEverything the work said, every step's words joined: its narration and its final reply together; null when it said nothing.
- Type
string | null
answerstring | nullmay be absentThe work's answer: its final reply, the words of its last step that said anything; null when none did. Absent from older events.
- Type
string | null
task.failedstream and webhookThe work failed: why, and what it cost.
task_idstringThe task (task_...).
- Type
string
statusstringmay be absentHow it ended, on the conversation's stream: completed, failed or stopped.
- Type
string
cost_usdnumber | nullmay be absentWhat it cost, in billed US dollars; null when not known yet.
- Type
number | null
cost_completebooleanmay be absentWhether every charge is in: false when the last ones can still land, on usage.updated.
- Type
boolean
reasonstringmay be absentWhy it failed, as a short code, such as disconnected.
- Type
string
messagestring | nullmay be absentMore about why, in plain words; null when there is no more.
- Type
string | null
titlestringmay be absentWhat the work was, when it failed before it started.
- Type
string
turn_idstringmay be absentThe turn that tried to start it (turn_...), when it failed before it started.
- Type
string
task.stoppedstream and webhookThe work was stopped: by you or a person, or by a limit, the credits running out or a policy, which its reason names.
task_idstringThe task (task_...).
- Type
string
statusstringmay be absentHow it ended, on the conversation's stream: completed, failed or stopped.
- Type
string
cost_usdnumber | nullmay be absentWhat it cost, in billed US dollars; null when not known yet.
- Type
number | null
cost_completebooleanmay be absentWhether every charge is in: false when the last ones can still land, on usage.updated.
- Type
boolean
reasonstringmay be absentWhy it stopped, when a limit or a policy stopped it rather than a person: max_turns, max_budget, credits_exhausted (the account's credits ran out) or hook_blocked.
- Type
string
messagestring | nullmay be absentMore about why, in plain words (a policy hook's own words); null when there is no more.
- Type
string | null
What Bash waits on
interaction.createdstream and webhookBash waits on someone: an approval, a question, an app to connect, a hand-off, or a call to your tool.
interaction_idstringWhat Bash waits on, to answer by its id (int_..., or call_... for a call to your tool).
- Type
string
typeInteractionTypeWhat answer it takes: approval, question, connect, handoff or tool_call.
- Type
InteractionType
task_idstringmay be absentThe task that asked (task_...).
- Type
string
turn_idstringmay be absentFor a call to your tool from Bash's reply: the turn (turn_...).
- Type
string
namestringmay be absentFor a call to your tool: the tool's name.
- Type
string
argumentsunknownmay be absentFor a call to your tool: what Bash passed it.
- Type
unknown
serverstringmay be absentFor a call to a tool of your MCP server in a test run, which Bash never runs for real there: the server's slug.
- Type
string
interaction.resolvedstream and webhookWhat Bash waited on was answered, or withdrawn.
interaction_idstringmay be absentWhat was answered, withdrawn or closed (int_... or call_...). Absent when interaction is sent instead.
- Type
string
interactionInteractionmay be absentFor an ask that settles without waking the work (a hand-off's verdict, a question the server asked), answered or withdrawn: the whole interaction, with its outcome. Webhook only.
- Type
Interaction
typeInteractionTypemay be absentFor a call to your tool: tool_call.
- Type
InteractionType
task_idstringmay be absentThe task that asked (task_...).
- Type
string
outcomestringmay be absentcancelled: its task's stop or failure, or a newer message, closed it unanswered. Absent when it was answered or withdrawn.
- Type
string
reasonstringmay be absentWith outcome cancelled: stopped or failed (its task ended), or superseded (a new message came in).
- Type
string
statusstringmay be absentFor a call to your tool: completed with your output, or failed with your error.
- Type
string
interaction.expiredstream and webhookA call to your tool went unanswered for too long.
interaction_idstringWhat expired unanswered (int_... or call_...).
- Type
string
typeInteractionTypemay be absentWhat answer it took.
- Type
InteractionType
task_idstringmay be absentThe task that asked (task_...).
- Type
string
The screen
screen.controlstream onlyWho has the screen: a person took the wheel, or Bash has it back.
by'user' | 'bash'Who drives the screen now: user, the person, or bash.
- Type
'user' | 'bash'
session_idstringmay be absentThe session the person drives from (ses_...).
- Type
string
Sessions
session.startedstream and webhookA session opened: a live screen, a voice call, or Bash inside your app.
session_idstringThe session (ses_...).
- Type
string
user_idstring | nullYour id for its user; null on your company's own Bash.
- Type
string | null
conversation_idstring | nullIts conversation (conv_...); null for a screen opened alone.
- Type
string | null
chatbooleanWhether it shows the conversation.
- Type
boolean
screenfalse | 'view' | 'control'Its screen: view, control, or false for none.
- Type
false | 'view' | 'control'
voicebooleanWhether your user can talk by voice.
- Type
boolean
memorybooleanWhether it shows what Bash remembers.
- Type
boolean
expires_atstringWhen its token stops working, as an ISO 8601 time.
- Type
string
session.endedstream and webhookA session ended. A voice call's carries its seconds and its transcript.
session_idstring | nullThe session (ses_...); null for a call that no session opened.
- Type
string | null
user_idstring | nullYour id for its user; null on your company's own Bash.
- Type
string | null
conversation_idstring | nullIts conversation (conv_...); null when it had none.
- Type
string | null
end_reasonstringWhy it ended: revoked when you ended the session, otherwise how its call ended, such as lost.
- Type
string
secondsnumbermay be absentFor a call: how long it lasted, in seconds.
- Type
number
transcript{ speaker: "user" | "bash"; text: string; }[]may be absentFor a call: what was said, in order, by user or bash.
- Type
{ speaker: "user" | "bash"; text: string; }[]
transcript_truncatedbooleanmay be absentFor a call: true when the transcript stops at its 100,000 characters.
- Type
boolean
Files
file.createdstream and webhookBash made a file: its id, its name and its task.
file_idstringThe file (file_...): read it with GET /v1/files/{file_id}.
- Type
string
task_idstringmay be absentThe task that made it (task_...).
- Type
string
filenamestring | nullIts name; null when it has none.
- Type
string | null
mime_typestring | nullIts type, such as application/pdf; null when unknown.
- Type
string | null
size_bytesnumber | nullIts size, in bytes; null when unknown.
- Type
number | null
Routines
routine.firedstream and webhookA routine ran, on its schedule or on your call.
routine_idstringThe routine (rtn_...).
- Type
string
run_idstringThis run of it.
- Type
string
conversation_idstringThe conversation the run posts into (conv_...).
- Type
string
user_idstring | nullYour id for its user; null on your company's own Bash.
- Type
string | null
turn_idstringThe turn the run started (turn_...).
- Type
string
Money
usage.updatedstream onlyCharges that landed after a turn settled, for the turn and its work.
delta_usdnumberWhat was just charged, in billed US dollars.
- Type
number
task_idstringmay be absentThe task it was charged to (task_...), when it was.
- Type
string
task_total_usdnumbermay be absentThat task's total so far, in billed US dollars.
- Type
number
conversation_total_usdnumber | nullThe conversation's total so far, in billed US dollars; null when not known.
- Type
number | null
user{ day: { spent_usd: number; cap_usd: number | null; remaining_usd: number | null }; month: { spent_usd: number; cap_usd: number | null; remaining_usd: number | null } } | nullThe spend, cap and what is left, today and this month, of the user the charge was billed to (your company's own Bash counts as one); null when the standing could not be read.
- Type
{ day: { spent_usd: number; cap_usd: number | null; remaining_usd: number | null }; month: { spent_usd: number; cap_usd: number | null; remaining_usd: number | null } } | null
as_ofstringWhen these numbers were read, as an ISO 8601 time.
- Type
string
usage.threshold_reachedwebhook onlySpend passed one of your alert thresholds.
scope'company' | 'user'Whose spend: company, all of your company's, or user, one user's.
- Type
'company' | 'user'
user_idstringmay be absentFor a user's alert: your id for the user.
- Type
string
period'day' | 'month'The period the cap is for: day or month (UTC).
- Type
'day' | 'month'
period_startstringWhen the period started, as an ISO 8601 time.
- Type
string
threshold_pctnumberThe share of the cap spent, in percent: one of your alert thresholds, or 100 at the cap.
- Type
number
spent_usdnumberWhat has been spent in the period, in billed US dollars.
- Type
number
cap_usdnumberThe cap, in US dollars.
- Type
number
usage.cap_reachedwebhook onlySpend reached one of your caps.
scope'company' | 'user'Whose spend: company, all of your company's, or user, one user's.
- Type
'company' | 'user'
user_idstringmay be absentFor a user's alert: your id for the user.
- Type
string
period'day' | 'month'The period the cap is for: day or month (UTC).
- Type
'day' | 'month'
period_startstringWhen the period started, as an ISO 8601 time.
- Type
string
threshold_pctnumberThe share of the cap spent, in percent: one of your alert thresholds, or 100 at the cap.
- Type
number
spent_usdnumberWhat has been spent in the period, in billed US dollars.
- Type
number
cap_usdnumberThe cap, in US dollars.
- Type
number
The conversation
conversation.statusstream and webhookThe conversation's status (idle, replying, working or waiting) and its turn's: turn_status is running, working, requires_action, completed, failed or stopped. Webhooks carry the turns that settle.
status'idle' | 'replying' | 'working' | 'waiting'What the conversation is doing now: idle, replying, working or waiting.
- Type
'idle' | 'replying' | 'working' | 'waiting'
turn_idstringmay be absentThe turn that changed it (turn_...).
- Type
string
turn_status'running' | 'working' | 'requires_action' | 'completed' | 'failed' | 'stopped'may be absentWhere that turn is now: running, working, requires_action, or settled as completed, failed or stopped.
- Type
'running' | 'working' | 'requires_action' | 'completed' | 'failed' | 'stopped'
dataunknownmay be absentWhen the turn settled: the data you asked for with output_schema.
- Type
unknown
outcome{ met: boolean; reason: string }may be absentWhen the turn settled: whether it met your success_criteria (met), and why (reason).
- Type
{ met: boolean; reason: string }
error{ code: string; message: string }may be absentWhen the turn failed: why, as a code and a message.
- Type
{ code: string; message: string }
usage{ turn_cost_usd: number; conversation_total_usd: number; cost_complete: boolean } | nullmay be absentWhen the turn settled: what it cost, the conversation's total, and whether every charge is in.
- Type
{ turn_cost_usd: number; conversation_total_usd: number; cost_complete: boolean } | null
Users
user.createdwebhook onlyA user was made, the first time you named them.
user_idstringYour id for the user Vestra just made, the first time you named them.
- Type
string
user.deletedwebhook onlyA user's erasure finished: their Bash, computer, memory and files are gone.
user_idstringYour id for the user who was erased.
- Type
string
completebooleanmay be absentWhether every part was erased; false when a part could not be, and it is retried.
- Type
boolean
Connected apps
connection.completedwebhook onlyAn app was connected.
user_idstring | nullYour id for the user who connected; null on your company's own Bash.
- Type
string | null
connection{ object: 'connection'; id: string; user_id: string | null; app: string; status: string; label: string | null; created_at: string }The connection made: its id (con_...), app, status, label and when it was made.
- Type
{ object: 'connection'; id: string; user_id: string | null; app: string; status: string; label: string | null; created_at: string }
connection.failedwebhook onlyConnecting an app failed.
user_idstring | nullYour id for the user; null on your company's own Bash.
- Type
string | null
appstringThe app that did not connect.
- Type
string
connection_idstring | nullThe connection that failed (con_...); null when none was made.
- Type
string | null
reasonstring | nullWhy, in plain words; null when the app did not say.
- Type
string | null
connection.removedwebhook onlyAn app was disconnected.
user_idstring | nullYour id for the user; null on your company's own Bash.
- Type
string | null
connection_idstringThe connection removed (con_...).
- Type
string
appstringIts app.
- Type
string
Memory
memory.observedwebhook onlyBash learned something new to remember about a user.
user_idstringYour id for the user Bash learned about.
- Type
string
task_idstringThe task it learned it in (task_...).
- Type
string
conversation_idstringmay be absentThat task's conversation (conv_...).
- Type
string
observationstringWhat Bash learned, in plain words: keep it in your memory, which your memory endpoint gives back.
- Type
string
kindstringWhat kind of fact it is, such as preference or identity.
- Type
string
sourcestringHow Bash learned it, such as agent_inferred.
- Type
string
observed_atstringWhen it learned it, as an ISO 8601 time.
- Type
string
Batches
batch.completedwebhook onlyEvery item of a batch has finished.
batch_idstringThe batch (bat_...).
- Type
string
status'completed' | 'cancelled'completed: every item finished. cancelled: you cancelled it.
- Type
'completed' | 'cancelled'
item_countnumberHow many items it had.
- Type
number
counts{ queued: number; running: number; succeeded: number; failed: number; cancelled: number }Its items, by status: queued, running, succeeded, failed and cancelled.
- Type
{ queued: number; running: number; succeeded: number; failed: number; cancelled: number }
Deployments
deployment.version_createdwebhook onlyA deployment has a new version.
deployment_idstringThe deployment (dep_...).
- Type
string
versionnumberThe new version.
- Type
number
manifest_sha256stringA fingerprint of the version's file: two versions with the same one are the same setup.
- Type
string
deployment.promotedwebhook onlyA version went live in its mode.
deployment_idstringThe deployment (dep_...).
- Type
string
from_versionnumber | nullThe version it ran before; null when none did.
- Type
number | null
to_versionnumberThe version it runs now.
- Type
number
became_defaultbooleanWhether this promotion made the deployment your company's default.
- Type
boolean
deployment.rolled_backwebhook onlyA deployment went back to an earlier version.
deployment_idstringThe deployment (dep_...).
- Type
string
from_versionnumber | nullThe version it ran before; null when none did.
- Type
number | null
to_versionnumberThe version it runs now.
- Type
number
Tests
test_run.completedwebhook onlyA test run finished, with how many scenarios passed. Its error_code is null unless the run ended in error: interrupted when it stopped reporting.
test_run_idstringThe test run (trun_...).
- Type
string
deployment_idstringThe deployment it tested (dep_...).
- Type
string
versionnumberThe version it tested.
- Type
number
status'passed' | 'failed' | 'error'passed: every test passed. failed: at least one did not. error: the run could not finish.
- Type
'passed' | 'failed' | 'error'
error_codestring | nullWhy the run could not finish, such as interrupted; null unless its status is error.
- Type
string | null
passednumberHow many tests passed.
- Type
number
totalnumberHow many tests it played.
- Type
number
promoted{ mode: 'live' | 'test'; version: number } | nullWhat the pass promoted, its mode and version; null when it promoted nothing.
- Type
{ mode: 'live' | 'test'; version: number } | null
became_defaultbooleanWhether that promotion made the deployment your company's default.
- Type
boolean
Keys
key.createdwebhook onlyA key was made.
key_idstringThe key (key_...).
- Type
string
namestring | nullmay be absentIts name; null when it has none.
- Type
string | null
key.revokedwebhook onlyA key was revoked.
key_idstringThe key that stopped working (key_...).
- Type
string
The stream itself
errorstream onlyThe stream's own error: its code and its message.
codestringA stable code to branch on.
- Type
string
messagestringWhat went wrong, in plain words.
- Type
string
turn_idstringmay be absentThe turn it happened in (turn_...).
- Type
string