> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# turn()

> **turn**(`input`, `options?`): `Promise`\<[`HarnessTurnResult`](/docs/agent-sdk/harness-sdk/harness/turn#harnessturnresult)\<`HarnessParsedOutput`\<`OutputDefinition`>>>

**Parameters**

| Parameter | Type |
| - | - |
| `input` | `string` |
| `options?` | [`HarnessTurnOptions`](/docs/agent-sdk/harness-sdk/harness/turn#harnessturnoptions)\<`TOOLS`, `OutputDefinition`> |

**Returns**
`Promise`\<[`HarnessTurnResult`](/docs/agent-sdk/harness-sdk/harness/turn#harnessturnresult)\<`HarnessParsedOutput`\<`OutputDefinition`>>>

## HarnessTurnOptions

Per-turn transport-neutral observation callbacks.

**Type Parameters**

| Type Parameter | Default type |
| - | - |
|  `TOOLS` *extends* `ToolSet` | `ToolSet` |
|  `OutputDefinition` *extends* `HarnessOutputDefinition` \| `undefined` | `undefined` |

**Properties**
**callbacks?**

> `optional` **callbacks?**: `Readonly`\<\{ `onFinish?`: `GenerateTextOnFinishCallback`\<`TOOLS`>; `onStart?`: `GenerateTextOnStartCallback`; `onStepFinish?`: `GenerateTextOnStepFinishCallback`\<`TOOLS`>; `onStepStart?`: `GenerateTextOnStepStartCallback`\<`TOOLS`>; `onToolCallFinish?`: `GenerateTextOnToolCallFinishCallback`\<`TOOLS`>; `onToolCallStart?`: `GenerateTextOnToolCallStartCallback`\<`TOOLS`>; }>

AI SDK lifecycle callbacks, chained after harness persistence work.

**onCancel?**

> `optional` **onCancel?**: (`error`) => `void` | `Promise`\<`void`>

Runs once after cleanup when the caller-owned signal cancels a turn.

**Parameters**

| Parameter | Type |
| - | - |
| `error` | [`HarnessCancellationError`](/docs/agent-sdk/harness-sdk/harness/turn#harnesscancellationerror) |

**Returns**
`void` | `Promise`\<`void`>

**onError?**

> `optional` **onError?**: (`error`) => `void` | `Promise`\<`void`>

Runs once after cleanup for non-cancellation failures.

**Parameters**

| Parameter | Type |
| - | - |
| `error` | `unknown` |

**Returns**
`void` | `Promise`\<`void`>

**onOutput?**

> `optional` **onOutput?**: (`output`) => `void` | `Promise`\<`void`>

Runs once after the complete successful output has been persistently journaled.

**Parameters**

| Parameter | Type |
| - | - |
| `output` | [`HarnessTurnResult`](/docs/agent-sdk/harness-sdk/harness/turn#harnessturnresult)\<`HarnessParsedOutput`\<`OutputDefinition`>> |

**Returns**
`void` | `Promise`\<`void`>

**onStepCommitted?**

> `optional` **onStepCommitted?**: (`step`) => `void` | `Promise`\<`void`>

Runs after the completed step has been persistently journaled.

**Parameters**

| Parameter | Type |
| - | - |
| `step` | [`HarnessStep`](/docs/agent-sdk/harness-sdk/harness/turn#harnessstep) |

**Returns**
`void` | `Promise`\<`void`>

**signal?**

> `optional` **signal?**: `AbortSignal`

Caller-owned cancellation signal passed to AI SDK without transport coupling.

**steps?**

> `optional` **steps?**: [`HarnessStepContext`](/docs/agent-sdk/harness-sdk/persistence/step-context#harnessstepcontext)

Persistent context supplied only by the harness run ledger.

## HarnessTurnResult

Transport-neutral result of a completed turn.

**Type Parameters**

| Type Parameter | Default type |
| - | - |
|  `Output` | `unknown` |

**Properties**
**finishReason**

> `readonly` **finishReason**: `FinishReason`

**journalThrough**

> `readonly` **journalThrough**: `number`

**output?**

> `readonly` `optional` **output?**: `Output`

Parsed AI SDK output when a structured output mode is configured.

**stepCount**

> `readonly` **stepCount**: `number`

**text**

> `readonly` **text**: `string`

**usage**

> `readonly` **usage**: [`HarnessUsage`](/docs/agent-sdk/harness-sdk/harness/turn#harnessusage)

## HarnessUsage

Transport-safe aggregate token usage for a completed turn.

**Properties**
**inputTokens**

> `readonly` **inputTokens**: `number` | `undefined`

**outputTokens**

> `readonly` **outputTokens**: `number` | `undefined`

**totalTokens**

> `readonly` **totalTokens**: `number` | `undefined`

## HarnessStep

One completed model step, excluding provider request/response bodies and metadata.

**Properties**
**finishReason**

> **finishReason**: `FinishReason`

**journalThrough**

> **journalThrough**: `number`

**number**

> **number**: `number`

**text**

> **text**: `string`

**toolCalls**

> **toolCalls**: readonly `Readonly`\<\{ `id`: `string`; `input`: `unknown`; `name`: `string`; }>\[]

**toolResults**

> **toolResults**: readonly `Readonly`\<\{ `id`: `string`; `isError`: `boolean`; `name`: `string`; `output`: `unknown`; }>\[]

## HarnessStepLimitError

Raised after the final allowed model step still requests executable tools.

**Constructors**
**Constructor**

> **new HarnessStepLimitError**(`maxSteps`, `completedSteps`, `lastToolCalls`): `HarnessStepLimitError`

**Parameters**

| Parameter | Type |
| - | - |
| `maxSteps` | `number` |
| `completedSteps` | `number` |
| `lastToolCalls` | readonly `Readonly`\<\{ `id`: `string`; `name`: `string`; }>\[] |

**Returns**
`HarnessStepLimitError`

**Properties**
**cause?**

> `optional` **cause?**: `unknown`

**code**

> `readonly` **code**: `"HARNESS_STEP_LIMIT"`

**completedSteps**

> `readonly` **completedSteps**: `number`

**lastToolCalls**

> `readonly` **lastToolCalls**: readonly `Readonly`\<\{ `id`: `string`; `name`: `string`; }>\[]

**maxSteps**

> `readonly` **maxSteps**: `number`

**message**

> **message**: `string`

**name**

> **name**: `string`

**stack?**

> `optional` **stack?**: `string`

**stackTraceLimit**

> `static` **stackTraceLimit**: `number`

The `Error.stackTraceLimit` property specifies the number of stack frames
collected by a stack trace (whether generated by `new Error().stack` or
`Error.captureStackTrace(obj)`).

The default value is `10` but may be set to any valid JavaScript number. Changes
will affect any stack trace captured *after* the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will
not capture any frames.

**Methods**
**captureStackTrace()**

> `static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void`

Creates a `.stack` property on `targetObject`, which when accessed returns
a string representing the location in the code at which
`Error.captureStackTrace()` was called.

```js theme={null}
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`
```

The first line of the trace will be prefixed with
`${myObject.name}: ${myObject.message}`.

The optional `constructorOpt` argument accepts a function. If given, all frames
above `constructorOpt`, including `constructorOpt`, will be omitted from the
generated stack trace.

The `constructorOpt` argument is useful for hiding implementation
details of error generation from the user. For instance:

```js theme={null}
function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
```

**Parameters**

| Parameter | Type |
| - | - |
| `targetObject` | `object` |
| `constructorOpt?` | `Function` |

**Returns**
`void`

**prepareStackTrace()**

> `static` **prepareStackTrace**(`err`, `stackTraces`): `any`

**Parameters**

| Parameter | Type |
| - | - |
| `err` | `Error` |
| `stackTraces` | `CallSite`\[] |

**Returns**
`any`

**See**
[https://v8.dev/docs/stack-trace-api#customizing-stack-traces](https://v8.dev/docs/stack-trace-api#customizing-stack-traces)

## HarnessProviderError

Stable provider-boundary error containing only allowlisted diagnostics.

**Constructors**
**Constructor**

> **new HarnessProviderError**(`diagnostics`): `HarnessProviderError`

**Parameters**

| Parameter | Type |
| - | - |
| `diagnostics` | [`HarnessProviderDiagnostics`](/docs/agent-sdk/harness-sdk/harness/turn#harnessproviderdiagnostics) |

**Returns**
`HarnessProviderError`

**Properties**
**cause?**

> `optional` **cause?**: `unknown`

**code**

> `readonly` **code**: `"HARNESS_PROVIDER_ERROR"`

**diagnostics**

> `readonly` **diagnostics**: [`HarnessProviderDiagnostics`](/docs/agent-sdk/harness-sdk/harness/turn#harnessproviderdiagnostics)

**message**

> **message**: `string`

**name**

> **name**: `string`

**stack?**

> `optional` **stack?**: `string`

**stackTraceLimit**

> `static` **stackTraceLimit**: `number`

The `Error.stackTraceLimit` property specifies the number of stack frames
collected by a stack trace (whether generated by `new Error().stack` or
`Error.captureStackTrace(obj)`).

The default value is `10` but may be set to any valid JavaScript number. Changes
will affect any stack trace captured *after* the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will
not capture any frames.

**Methods**
**captureStackTrace()**

> `static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void`

Creates a `.stack` property on `targetObject`, which when accessed returns
a string representing the location in the code at which
`Error.captureStackTrace()` was called.

```js theme={null}
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`
```

The first line of the trace will be prefixed with
`${myObject.name}: ${myObject.message}`.

The optional `constructorOpt` argument accepts a function. If given, all frames
above `constructorOpt`, including `constructorOpt`, will be omitted from the
generated stack trace.

The `constructorOpt` argument is useful for hiding implementation
details of error generation from the user. For instance:

```js theme={null}
function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
```

**Parameters**

| Parameter | Type |
| - | - |
| `targetObject` | `object` |
| `constructorOpt?` | `Function` |

**Returns**
`void`

**prepareStackTrace()**

> `static` **prepareStackTrace**(`err`, `stackTraces`): `any`

**Parameters**

| Parameter | Type |
| - | - |
| `err` | `Error` |
| `stackTraces` | `CallSite`\[] |

**Returns**
`any`

**See**
[https://v8.dev/docs/stack-trace-api#customizing-stack-traces](https://v8.dev/docs/stack-trace-api#customizing-stack-traces)

## HarnessProviderDiagnostics

Safe provider failure fields. Raw causes, URLs, headers, and bodies are never retained.

**Properties**
**causeName**

> `readonly` **causeName**: `string`

**modelId**

> `readonly` **modelId**: `string`

**provider**

> `readonly` **provider**: `string`

**retryable?**

> `readonly` `optional` **retryable?**: `boolean`

**statusCode?**

> `readonly` `optional` **statusCode?**: `number`

## HarnessToolOutputError

Local tool failure used when a successful execution returns an unsafe output.

**Constructors**
**Constructor**

> **new HarnessToolOutputError**(`toolName`): `HarnessToolOutputError`

**Parameters**

| Parameter | Type |
| - | - |
| `toolName` | `string` |

**Returns**
`HarnessToolOutputError`

**Properties**
**cause?**

> `optional` **cause?**: `unknown`

**code**

> `readonly` **code**: `"HARNESS_TOOL_OUTPUT_ERROR"`

**message**

> **message**: `string`

**name**

> **name**: `string`

**stack?**

> `optional` **stack?**: `string`

**toolName**

> `readonly` **toolName**: `string`

**stackTraceLimit**

> `static` **stackTraceLimit**: `number`

The `Error.stackTraceLimit` property specifies the number of stack frames
collected by a stack trace (whether generated by `new Error().stack` or
`Error.captureStackTrace(obj)`).

The default value is `10` but may be set to any valid JavaScript number. Changes
will affect any stack trace captured *after* the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will
not capture any frames.

**Methods**
**captureStackTrace()**

> `static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void`

Creates a `.stack` property on `targetObject`, which when accessed returns
a string representing the location in the code at which
`Error.captureStackTrace()` was called.

```js theme={null}
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`
```

The first line of the trace will be prefixed with
`${myObject.name}: ${myObject.message}`.

The optional `constructorOpt` argument accepts a function. If given, all frames
above `constructorOpt`, including `constructorOpt`, will be omitted from the
generated stack trace.

The `constructorOpt` argument is useful for hiding implementation
details of error generation from the user. For instance:

```js theme={null}
function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
```

**Parameters**

| Parameter | Type |
| - | - |
| `targetObject` | `object` |
| `constructorOpt?` | `Function` |

**Returns**
`void`

**prepareStackTrace()**

> `static` **prepareStackTrace**(`err`, `stackTraces`): `any`

**Parameters**

| Parameter | Type |
| - | - |
| `err` | `Error` |
| `stackTraces` | `CallSite`\[] |

**Returns**
`any`

**See**
[https://v8.dev/docs/stack-trace-api#customizing-stack-traces](https://v8.dev/docs/stack-trace-api#customizing-stack-traces)

## HarnessCancellationError

Stable cancellation classification for an aborted caller-owned turn signal.

**Constructors**
**Constructor**

> **new HarnessCancellationError**(): `HarnessCancellationError`

**Returns**
`HarnessCancellationError`

**Properties**
**cause?**

> `optional` **cause?**: `unknown`

**code**

> `readonly` **code**: `"HARNESS_CANCELLED"`

**message**

> **message**: `string`

**name**

> **name**: `string`

**stack?**

> `optional` **stack?**: `string`

**stackTraceLimit**

> `static` **stackTraceLimit**: `number`

The `Error.stackTraceLimit` property specifies the number of stack frames
collected by a stack trace (whether generated by `new Error().stack` or
`Error.captureStackTrace(obj)`).

The default value is `10` but may be set to any valid JavaScript number. Changes
will affect any stack trace captured *after* the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will
not capture any frames.

**Methods**
**captureStackTrace()**

> `static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void`

Creates a `.stack` property on `targetObject`, which when accessed returns
a string representing the location in the code at which
`Error.captureStackTrace()` was called.

```js theme={null}
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`
```

The first line of the trace will be prefixed with
`${myObject.name}: ${myObject.message}`.

The optional `constructorOpt` argument accepts a function. If given, all frames
above `constructorOpt`, including `constructorOpt`, will be omitted from the
generated stack trace.

The `constructorOpt` argument is useful for hiding implementation
details of error generation from the user. For instance:

```js theme={null}
function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
```

**Parameters**

| Parameter | Type |
| - | - |
| `targetObject` | `object` |
| `constructorOpt?` | `Function` |

**Returns**
`void`

**prepareStackTrace()**

> `static` **prepareStackTrace**(`err`, `stackTraces`): `any`

**Parameters**

| Parameter | Type |
| - | - |
| `err` | `Error` |
| `stackTraces` | `CallSite`\[] |

**Returns**
`any`

**See**
[https://v8.dev/docs/stack-trace-api#customizing-stack-traces](https://v8.dev/docs/stack-trace-api#customizing-stack-traces)

## HarnessObserverError

Stable aggregate retaining a primary turn failure when its observer also fails.

**Constructors**
**Constructor**

> **new HarnessObserverError**(`primary`, `observer`, `phase`): `HarnessObserverError`

**Parameters**

| Parameter | Type |
| - | - |
| `primary` | `unknown` |
| `observer` | `unknown` |
| `phase` | `"cancel"` \| `"error"` |

**Returns**
`HarnessObserverError`

**Properties**
**cause?**

> `optional` **cause?**: `unknown`

**code**

> `readonly` **code**: `"HARNESS_OBSERVER_ERROR"`

**message**

> **message**: `string`

**name**

> **name**: `string`

**observer**

> `readonly` **observer**: `unknown`

**phase**

> `readonly` **phase**: `"cancel"` | `"error"`

**primary**

> `readonly` **primary**: `unknown`

**stack?**

> `optional` **stack?**: `string`

**stackTraceLimit**

> `static` **stackTraceLimit**: `number`

The `Error.stackTraceLimit` property specifies the number of stack frames
collected by a stack trace (whether generated by `new Error().stack` or
`Error.captureStackTrace(obj)`).

The default value is `10` but may be set to any valid JavaScript number. Changes
will affect any stack trace captured *after* the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will
not capture any frames.

**Methods**
**captureStackTrace()**

> `static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void`

Creates a `.stack` property on `targetObject`, which when accessed returns
a string representing the location in the code at which
`Error.captureStackTrace()` was called.

```js theme={null}
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`
```

The first line of the trace will be prefixed with
`${myObject.name}: ${myObject.message}`.

The optional `constructorOpt` argument accepts a function. If given, all frames
above `constructorOpt`, including `constructorOpt`, will be omitted from the
generated stack trace.

The `constructorOpt` argument is useful for hiding implementation
details of error generation from the user. For instance:

```js theme={null}
function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
```

**Parameters**

| Parameter | Type |
| - | - |
| `targetObject` | `object` |
| `constructorOpt?` | `Function` |

**Returns**
`void`

**prepareStackTrace()**

> `static` **prepareStackTrace**(`err`, `stackTraces`): `any`

**Parameters**

| Parameter | Type |
| - | - |
| `err` | `Error` |
| `stackTraces` | `CallSite`\[] |

**Returns**
`any`

**See**
[https://v8.dev/docs/stack-trace-api#customizing-stack-traces](https://v8.dev/docs/stack-trace-api#customizing-stack-traces)