Runs, events and streaming
Execute, event stream, run states, stream cuts and recovery, threads, input limits and what callers actually see.
Endpoints (gateway, prefix /api/v1)
| Call | Purpose |
|---|---|
POST /execute {instance_id, input, thread_id?, conversation_id?, skill?, attachments?} |
start a run -> {run_id, thread_id, status:"RUNNING"} (may be wrapped in data) |
GET /events/{run_id} (SSE, Last-Event-ID) |
live events; frames id: <seq>, data: {type, payload, run_id, sequence, timestamp}; : keepalive every 15 s |
GET /runs/{run_id} |
status QUEUED RUNNING WAITING_USER WAITING_AUTH COMPLETED FAILED CANCELLED REJECTED |
GET /runs/{run_id}/events?after=<seq> |
stored events (page with has_more) |
GET /runs/{id}/trace, /runs/{id}/debug/stream, /runs/compare?left=&right=, POST /runs/{id}/debug/{pause,resume,step,abort} |
debugging (novaos-cli debug trace/watch/compare) |
GET /conversations[?instance_id,status,limit,cursor], /conversations/{id}, /conversations/{id}/messages, PATCH /conversations/{id} |
platform conversation store |
POST /conversations/{thread_id}/hitl {"approved": bool} |
native human decision for a paused run (human token only) |
GET /instances, GET /llm/models, GET /mcp/tools, GET /mcp/servers, GET /streaming/health |
discovery and health |
Event types callers see
status (payload.message progress label; payload.status), message.delta / chunk (payload.content), message.final (full answer under payload.content; some 2.x runs have none), error (payload.message|error|skill_error), done (payload.run), usage ({input_tokens, output_tokens, cost_usd, model} if the agent emits it).
Mapping from the agent: WORKING + platform progress part -> status; output artifact text -> message.delta; COMPLETED -> done (live) or status COMPLETED + message.final (replay); FAILED -> error with skill_error; skill-metadata parts on WORKING -> nothing.
Boot labels: "Resolving agent...", "Preparing configuration...", "Creating agent instance..." (cold start only), "Executing agent...".
Limits
inputis a STRING, max 100,000 chars (keep turns < 60k; let the agent fetch large context via read-named MCP tools). Gateway request max ~500k. Result (Temporal activity) max ~4 MB.- Agent timeout cap 600 s; streams cut at ~300 s (often
SSL DECRYPTION_FAILED_OR_BAD_RECORD_MAC) while the run continues; no bytes for ~30 s -> cancelled; response headers within 30 s.
Recovery: never re-run
- On a closed stream or transport error: reconnect with
Last-Event-ID(up to 3 times, backoff 1-8 s). - Then poll
GET /runs/{id}every ~3 s (heartbeat to your UI every 15 s) for up to ~330 s. - When terminal: read
/runs/{id}/eventsand replay only what the stream missed (result-bearing events), deduping markers. - Still running after the deadline: tell the user the answer is late; do NOT resubmit.
- Cut before the first frame (no run id yet): resend with the SAME idempotency key (joins the existing run).
Tools:
novaos_run_wait,novaos_ask_agent(both follow these rules).
Threads
- Thread ids must be gateway-created: an unknown
thread_idreturns 404THREAD_NOT_FOUND. Send no thread on the first run, store the returnedthread_id, map your conversation id to it, and on 404 retry once without it. (Client-made UUIDs worked in some apps/periods: do not rely on it.) - A thread does NOT pin a pod. Keep two ids per conversation: your own (sent inside the payload for agent memory) and the gateway run thread.
- "Agent execution dispatch failed" (503
TEMPORAL_DISPATCH_FAILED) or a dropped connection ~1 s after POST usually means a stale thread: retry once on a fresh thread and persist it; stop after two refusals. - Never prefetch/prewarm on a chat's own thread: NovaOS replayed the prefetch result as the next answer (ClickUp z95t6g7thr).
History
NovaOS stores only the FIRST stream frame of a reply as the thread's assistant message, and service accounts cannot list conversations. Keep conversation history in your own database and send the relevant history (plus a rolling summary) in each input. Tool: novaos_ask_agent {conversation: "..."} keeps a local history for you.
Native human-in-the-loop
Run state WAITING_USER (input) or WAITING_AUTH (tool confirmation or external sign-in). Decision: GET /runs/{id} -> thread_id -> POST /conversations/{thread_id}/hitl {"approved": true|false} with a HUMAN token (SA cannot approve). 200 {"ok":true} only acknowledges: verify by reading the run. Chat text "yes" is not an approval unless your app converts it. Tool: novaos_hitl_decide.