Pauses and control
Cancel a turn, resolve a paused turn, and know what a lost tool call does.
await session.cancel({ idempotencyKey, reason: "user stopped" });Cancellation is cooperative. A tool call already sent may have taken effect:
each call still running, or held for approval, ends with a tool.completed
whose status is cancelled. A later message starts another turn from the
state preceding the cancelled turn. Cancelling a flow cancels its running
agents and branches.
A cancel ends the turn, not the session's queue: messages sent while the turn ran stay queued and start the next turn. See Messages while a turn runs.
Tool call delivery
The Runtime delivers each MCP and HTTP tool call at least once. When a crash, a
shutdown, or a lost hop inside the Runtime interrupts a call, the Runtime sends
it again with the same key, up to 3 sends in all. Your service sees the key as
Idempotency-Key on an HTTP tool request, and
an MCP server sees it as _meta["nylorun/idempotency-key"] on tools/call. A
tool that honors the key acts once.
What the model sees when a call does not end with an answer:
| Call | Result the model sees |
|---|---|
| MCP or HTTP call interrupted inside the Runtime | Sent again with the same key. After 3 sends, tool.interrupted: the call may have run. |
| Sandbox tool, or a tool the harness or the Runtime runs itself, interrupted by a crash | tool.interrupted at once. It is never run twice; the model decides whether to call it again. |
| HTTP tool sent, then the connection to your service lost | http.lost: the call may have run. |
| MCP tool sent, then the connection to the server lost | mcp.lost: the call may have run. |
| Refused by the tool policy, or denied by a person | tool.denied, never sent. |
Each is a failed tool result with its code, and the turn goes on. A tool call
never leaves the session waiting on an unknown outcome. attempts above 1 on
tool.completed, or in session.toolCalls(),
marks a call that may have acted twice if the tool ignored the key. Other MCP
failures are coded tool errors too; see MCP.
A model call is different. When a crash loses a model call's outcome and the
gateway cannot recover it, the session is uncertain, with an
effect.uncertain event, and starts no new turn. A message sent meanwhile is
queued ({ status: "queued" }). Cancel the turn to go on; the queued messages
then start the next one.
Resolve a pause
A turn pauses with turn.paused when the
tool policy holds a tool call for a person, with one
approval interaction per held call. While it waits, new messages queue.
session.pending() lists the open interactions. Answer each one from your
backend:
await session.approve(interactionId, true);
await session.respond(interactionId, { note: "Need a manager" });| Interaction | Answer |
|---|---|
approval | session.approve(interactionId, approved, { idempotencyKey? }). Approved, the held call is sent as the person saw it. Denied, it fails to the model as tool.denied. |
response | session.respond(interactionId, value, { idempotencyKey? }) with any JSON value. |
The options are optional: without an idempotencyKey, each call makes its
own. Pass one to retry an answer safely, such as after a network error.
From a terminal, npx nylorun sessions approve <id> <interaction> [--deny]
and npx nylorun sessions respond <id> <interaction> <json> answer the same
way.
An approval for an MCP call names the tool by server and tool, the
server's own name for it, and its prompt reads Approve <server> / <tool>?;
toolName stays the name the model called it by. Studio's approval card shows
server / tool, with "as <toolName>" when the two differ.
An answer for an interaction the session is not waiting on is 409. A held
call waits without holding a process, so an answer can come after a Runtime
restart. Studio shows an approval card with Approve and Deny for each
held call. Which calls are held, and how to write the rules, is on
Tool policy.
In a flow, session.pending() on the flow's session lists
the held calls of its agents too, each with the sessionId that owns it.
Answer on that session: client.session(sessionId).approve(…).