NovaOS MCP
Field guide

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

  • input is 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

  1. On a closed stream or transport error: reconnect with Last-Event-ID (up to 3 times, backoff 1-8 s).
  2. Then poll GET /runs/{id} every ~3 s (heartbeat to your UI every 15 s) for up to ~330 s.
  3. When terminal: read /runs/{id}/events and replay only what the stream missed (result-bearing events), deduping markers.
  4. Still running after the deadline: tell the user the answer is late; do NOT resubmit.
  5. 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_id returns 404 THREAD_NOT_FOUND. Send no thread on the first run, store the returned thread_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.