Stopping a Turn

session.stop() stops the currently running Turn and cancels queued input that has not yet been absorbed by that Turn.

const turn = await session.prompt({ query: "Run a long task" });

const stop_result = await session.stop();
console.log(stop_result);

const result = await turn.finished;

Return value

type AgentSessionStopResult = {
  stopped: boolean;
  turn_id?: string;
  cancelled_queued_prompts: number;
  reason: "stopped" | "idle";
};

Input queue semantics

When users submit input consecutively, some input may already be merged into the current Turn as steering and some may still await the next Turn. Stop uses this boundary:

Input already absorbed by the current Turn -> stops with that Turn
Input still queued and not absorbed         -> is cancelled and never starts automatically

So a Stop button does not immediately start another execution because text remains in the queue. If a product must preserve a draft, keep it in UI draft state before calling stop() rather than relying on the SDK queue.

Final state

A stopped Turn still settles turn.finished:

const result = await turn.finished;

console.log(result.success); // false
console.log(result.error);   // usually Turn stopped

The subscription also receives variant: "turn", type: "finish", status: "stopped". Never leave code awaiting finished suspended because a stop occurred.

Calling stop() on an idle Session does not throw. It returns stopped: false and reason: "idle", making a UI stop action idempotent.