# drive

Run one root turn through the SDK's turn inbox.

`runtime.drive(next)` runs the session's next turn to an outcome. A turn that a previous runtime left in progress resumes first. Otherwise `drive` starts `next`, or the first pending turn. Only one `drive` runs at a time, so a host calls it in a loop until the queue is empty.

```ts title="host.ts"
import type { AgentRuntime } from 'nanocode-wasm'

declare const runtime: AgentRuntime

// Drives pending turns until none remain
for (;;) {
  const next = (await runtime.pending('owner'))[0]
  if (!next) break
  const driven = await runtime.drive(next.report.request_id)
  // 1. The runtime disposed itself, so reopen the session in a new
  // instance
  if (driven.retry)
    throw new Error('reopen the runtime from its checkpoint')
  // 2. The turn waits on a retry delay, so drive it again later
  if (driven.waiting)
    await new Promise((resolve) => setTimeout(resolve, 500))
}
```

## Signature

```ts
// Requires an open session
drive(next?: string): Promise<Driven>
```

## Parameters

### next

* **Type:** `string`

The request ID to start. Without it, `drive` starts the first pending turn in the scope. A turn that is already in progress in the agent runtime runs before `next`.

```ts
// Starts the first pending turn
const driven = await runtime.drive()
```

## Returns

* **Type:** `Promise<Driven>`

```ts
type Driven = {
  // Another drive is running
  busy?: boolean
  // The turn reached a final status
  finished?: TurnView
  // No turn was pending
  idle?: boolean
  // The turn that waits, resumed, or must retry
  request_id?: string
  // A turn from a previous runtime resumed
  resumed?: string
  // The runtime disposed itself
  retry?: boolean
  // The turn waits on a delay, or another drive is running
  waiting?: boolean
}
```

| Result                          | Meaning                                                                           |
| ------------------------------- | --------------------------------------------------------------------------------- |
| `{ idle: true }`                | No turn was pending.                                                              |
| `{ waiting: true, busy: true }` | Another `drive` is running. Drive again after it returns.                         |
| `{ finished }`                  | The turn ended as `completed`, `failed`, or `cancelled`.                          |
| `{ resumed }`                   | A turn that a previous runtime left in progress ran to an outcome.                |
| `{ waiting: true, request_id }` | The turn waits, for example on a model retry delay. Drive it again after a delay. |
| `{ retry: true }`               | The turn was interrupted or the command failed. The runtime disposed itself.      |

### finished

* **Type:** `TurnView`

The finished turn. `report.status` is `completed`, `failed`, or `cancelled`. A completed report has `ok` with `session_id`, `model`, and `message`, a failed report has `error`, and a cancelled report has `cancelled: true`. [`options.finishing`](/docs/api/wasm/open#optionsfinishing) adds fields.

```ts
import type { Driven } from 'nanocode-wasm'

declare const driven: Driven

// Reads the final message of a completed turn
const report = driven.finished?.report as
  | { ok?: { message: string } }
  | undefined
console.log(report?.ok?.message)
```

### retry

* **Type:** `boolean`

`true` when the SDK reports the turn as interrupted, such as when its events did not drain, or when the `drive` command itself failed. Before it returns, `drive` disposes the runtime. The host instantiates a new runtime, which resumes the turn from its checkpoint on its first `drive`.

```ts
import type { Driven } from 'nanocode-wasm'

declare const driven: Driven
declare function reopen(): Promise<void>

// The old runtime is closed
if (driven.retry) await reopen()
```

## Errors

`drive` throws if the runtime is closed: the failure that closed it, or `agent runtime is closed`. A failure inside the command returns `{ retry: true }` instead of a rejection. Calling `drive` before `open` returns `{ retry: true }` and disposes the runtime.

```ts
import type { AgentRuntime } from 'nanocode-wasm'

declare const runtime: AgentRuntime

// Checks the runtime before driving it
if (!runtime.closed) await runtime.drive()
```