nvoken
DocumentationHow turns end

Concepts

How turns end

Distinguish completed, incomplete, failed, and cancelled Turns, and understand waiting and budget holds.

Turn status is the authoritative lifecycle:

StatusMeaning
queuedAccepted and waiting for an execution attempt
runningThe model-and-tool loop is active
waitingA host tool result is required; no worker is held
budget_holdA resumable consumption limit or credit check stopped progress
completedThe model finished, or an interrupt ended work at a clean boundary
incompleteA configured limit ended work cleanly; partial output is valid
failedWork could not end cleanly; inspect error
cancelledThe caller discarded unfinished work

completed, incomplete, failed, and cancelled are final. Prefer the SDK's isTerminalTurnStatus() or the stream event's terminal signal to maintaining your own status list.

Interrupt and cancel mean different things

Interrupt asks a running Turn to stop at the next clean boundary. The Turn ends completed with stopReason: "interrupted", and valid work can carry into a Conversation's next Turn.

Cancel settles the Turn as cancelled and excludes unfinished work from later Conversation context. Use it when the work is no longer wanted.

Waiting and budget holds are not terminal

Submit required host-tool results to move a waiting Turn back to queued. Increase an allowed limit or add credits to release a budget_hold. Deadlines pause while a Turn is on budget hold.

Read the final result instead of treating a closed network connection as the outcome.