Awaiting agent events (runtime.agent.await_event)
The supervising MCP client learns each hosted-agent output event event-driven, instead of polling runtime.session.log. The extension forwards agent-output events to the bridge over its WebSocket; the bridge queues them per runtime with a monotonic cursor; a blocking await_event tool returns them.
The await-loop
cursor = null # first call: watch only future events
loop:
r = runtime.agent.await_event(target_url_contains=..., cursor=cursor, timeout_ms=25000)
if r.value.idle:
# the agent has been silent for timeout_ms — this IS the stall signal.
# act on it (screenshot, nudge, report) then loop again with the same cursor.
else:
for event in r.value.events:
handle(event) # report to the user / correct the agent / etc.
cursor = r.value.cursor # advance so the next call returns only newer events
cursor— the last eventseqyou have seen. The call returns events withseq > cursor. Omit it on the first call to watch only future events; pass-1to replay the retained queue from the start.timeout_ms— how long to block before returning idle (default 25000, clamped [1000, 60000]).- Returned
idle: trueafter silence is the stall signal — the case where the agent went quiet with work unfinished. Screenshot / nudge / report on it.
Event shape
Each event: { seq, ts, kind, payload }.
| kind | payload | meaning |
|---|---|---|
transcript | { role: "assistant", text } | an agent response |
tool | { name, ok, error } | a completed tool call |
refusal | { tool, reason } | a policy-exception refusal |
lifecycle | { state } | session started/stopped/idle/error |
events_dropped | { count } | queue overflow marker (you fell > cap behind) |
Realtime deltas, audio-transcript chunks, user-role transcripts (your own injected prompts), and heartbeats are NOT forwarded — the stream is agent output only.
Notes
- The queue is in-memory and per runtime; a bridge restart resets cursors.
await_eventnever consumes events (read-only cursor); multiple reads with the same cursor return the same backlog.- Routing: pass
target_runtime_idortarget_url_containsto pick the runtime, else the active tab is used. An unresolvable runtime returns an error immediately (it does not block waiting for one to appear).