NylorunDocsBeta
RunSessions

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:

CallResult the model sees
MCP or HTTP call interrupted inside the RuntimeSent 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 crashtool.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 losthttp.lost: the call may have run.
MCP tool sent, then the connection to the server lostmcp.lost: the call may have run.
Refused by the tool policy, or denied by a persontool.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" });
InteractionAnswer
approvalsession.approve(interactionId, approved, { idempotencyKey? }). Approved, the held call is sent as the person saw it. Denied, it fails to the model as tool.denied.
responsesession.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(…).

Next step

On this page