--- url: 'https://adk.nht.io/api/@nhtio/adk/types/interfaces/TurnContext.md' description: >- The validated, strongly-typed context object threaded through every middleware step in a single agent turn. --- # Interface: TurnContext Defined in: [lib/contracts/turn\_runner\_context.ts:329](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L329) The validated, strongly-typed context object threaded through every middleware step in a single agent turn. ## Remarks Constructed from a [RawTurnContext](RawTurnContext.md) by [@nhtio/adk!TurnRunner.run](../../turn_runner/classes/TurnRunner.md#run). Middleware functions receive this object and use it to read and share state across pipeline steps. ## Properties | Property | Modifier | Type | Description | Defined in | | ------------------------------------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `abort` | `readonly` | (`reason?`: `unknown`) => `void` | Aborts the turn's `AbortController` with the supplied reason. Middleware should call this when refusing the turn — the runner reads `aborted` between every stage and short-circuits cleanly: `turnEnd` still fires, no `error` event is emitted, and during dispatch `dispatchEnd.status === 'aborted'` carries the operational signal. | [lib/contracts/turn\_runner\_context.ts:672](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L672) | | `aborted` | `readonly` | `boolean` | `true` when the turn's `AbortController` signal has fired. | [lib/contracts/turn\_runner\_context.ts:663](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L663) | | `abortSignal` | `readonly` | `AbortSignal` | The `AbortSignal` from the turn's `AbortController`. | [lib/contracts/turn\_runner\_context.ts:665](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L665) | | `deleteMemory` | `readonly` | (`id`: `string`) => `void` | `Promise`<`void`> | Removes a memory from the persistence layer by ID. | [lib/contracts/turn\_runner\_context.ts:714](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L714) | | `deleteMessage` | `readonly` | (`id`: `string`) => `void` | `Promise`<`void`> | Removes a message from the persistence layer by ID. | [lib/contracts/turn\_runner\_context.ts:728](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L728) | | `deleteRetrievable` | `readonly` | (`id`: `string`) => `void` | `Promise`<`void`> | Removes a retrievable record from the persistence layer by ID. | [lib/contracts/turn\_runner\_context.ts:722](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L722) | | `deleteStandingInstruction` | `readonly` | (`v`: `string` | [`Tokenizable`](../../common/classes/Tokenizable.md)) => `void` | `Promise`<`void`> | Removes a standing instruction from the persistence layer. | [lib/contracts/turn\_runner\_context.ts:708](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L708) | | `deleteThought` | `readonly` | (`id`: `string`) => `void` | `Promise`<`void`> | Removes a thought from the persistence layer by ID. | [lib/contracts/turn\_runner\_context.ts:734](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L734) | | `deleteToolCall` | `readonly` | (`id`: `string`) => `void` | `Promise`<`void`> | Removes a tool call from the persistence layer by ID. | [lib/contracts/turn\_runner\_context.ts:740](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L740) | | `emitMessage` | `readonly` | [`EmitMessageFn`](../../turn_runner/type-aliases/EmitMessageFn.md) | Emits a `message` event on the runner; may be called at any point during the turn. | [lib/contracts/turn\_runner\_context.ts:760](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L760) | | `emitThought` | `readonly` | [`EmitThoughtFn`](../../turn_runner/type-aliases/EmitThoughtFn.md) | Emits a `thought` event on the runner; may be called at any point during the turn. | [lib/contracts/turn\_runner\_context.ts:762](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L762) | | `emitToolCall` | `readonly` | [`EmitToolCallFn`](../../turn_runner/type-aliases/EmitToolCallFn.md) | Emits a `toolCall` event on the runner; may be called at any point during the turn. | [lib/contracts/turn\_runner\_context.ts:764](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L764) | | `emitToolExecutionEnd` | `readonly` | [`EmitToolExecutionEndFn`](../../turn_runner/type-aliases/EmitToolExecutionEndFn.md) | Emits a `toolExecutionEnd` event on the observability bus; forwarded from `DispatchContext` by `DispatchRunner` when a tool finishes executing inside a dispatch. | [lib/contracts/turn\_runner\_context.ts:768](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L768) | | `emitToolExecutionStart` | `readonly` | [`EmitToolExecutionStartFn`](../../turn_runner/type-aliases/EmitToolExecutionStartFn.md) | Emits a `toolExecutionStart` event on the observability bus; forwarded from `DispatchContext` by `DispatchRunner` when a tool is invoked inside a dispatch. | [lib/contracts/turn\_runner\_context.ts:766](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L766) | | `fetchMemories` | `readonly` | () => | [`Memory`](../../common/classes/Memory.md)\[] | `Promise`<[`Memory`](../../common/classes/Memory.md)\[]> | Fetches memories relevant to this turn; delegates to the callback supplied at construction. | [lib/contracts/turn\_runner\_context.ts:690](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L690) | | `fetchMessages` | `readonly` | () => | [`Message`](../../common/classes/Message.md)\[] | `Promise`<[`Message`](../../common/classes/Message.md)\[]> | Fetches conversation messages relevant to this turn; delegates to the callback supplied at construction. | [lib/contracts/turn\_runner\_context.ts:692](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L692) | | `fetchRetrievables` | `readonly` | () => | [`Retrievable`](../../common/classes/Retrievable.md)\[] | `Promise`<[`Retrievable`](../../common/classes/Retrievable.md)\[]> | Fetches retrievable records relevant to this turn; delegates to the callback supplied at construction. | [lib/contracts/turn\_runner\_context.ts:716](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L716) | | `fetchThoughts` | `readonly` | () => | [`Thought`](../../common/classes/Thought.md)\[] | `Promise`<[`Thought`](../../common/classes/Thought.md)\[]> | Fetches thought traces relevant to this turn; delegates to the callback supplied at construction. | [lib/contracts/turn\_runner\_context.ts:694](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L694) | | `fetchToolCalls` | `readonly` | () => | [`ToolCall`](../../forge/classes/ToolCall.md)\[] | `Promise`<[`ToolCall`](../../forge/classes/ToolCall.md)\[]> | Fetches tool call records relevant to this turn; delegates to the callback supplied at construction. | [lib/contracts/turn\_runner\_context.ts:696](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L696) | | `fetchTools` | `readonly` | () => | [`Tool`](../../forge/classes/Tool.md)<[`SpooledArtifact`](../../spooled_artifact/classes/SpooledArtifact.md)>\[] | `Promise`<[`Tool`](../../forge/classes/Tool.md)<[`SpooledArtifact`](../../spooled_artifact/classes/SpooledArtifact.md)>\[]> | Fetches tools available for this turn; delegates to the callback supplied at construction. | [lib/contracts/turn\_runner\_context.ts:698](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L698) | | `id` | `readonly` | `string` | Unique identifier for this turn, generated as a UUIDv6 at construction time. | [lib/contracts/turn\_runner\_context.ts:661](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L661) | | `mutateMemory` | `readonly` | (`v`: [`Memory`](../../common/classes/Memory.md)) => `void` | `Promise`<`void`> | Updates an existing memory in the persistence layer. | [lib/contracts/turn\_runner\_context.ts:712](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L712) | | `mutateMessage` | `readonly` | (`v`: [`Message`](../../common/classes/Message.md)) => `void` | `Promise`<`void`> | Updates an existing message in the persistence layer. | [lib/contracts/turn\_runner\_context.ts:726](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L726) | | `mutateRetrievable` | `readonly` | (`v`: [`Retrievable`](../../common/classes/Retrievable.md)) => `void` | `Promise`<`void`> | Updates an existing retrievable record in the persistence layer. | [lib/contracts/turn\_runner\_context.ts:720](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L720) | | `mutateStandingInstruction` | `readonly` | (`v`: `string` | [`Tokenizable`](../../common/classes/Tokenizable.md)) => `void` | `Promise`<`void`> | Updates an existing standing instruction in the persistence layer. | [lib/contracts/turn\_runner\_context.ts:706](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L706) | | `mutateThought` | `readonly` | (`v`: [`Thought`](../../common/classes/Thought.md)) => `void` | `Promise`<`void`> | Updates an existing thought in the persistence layer. | [lib/contracts/turn\_runner\_context.ts:732](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L732) | | `mutateToolCall` | `readonly` | (`v`: [`ToolCall`](../../forge/classes/ToolCall.md)) => `void` | `Promise`<`void`> | Updates an existing tool call in the persistence layer. | [lib/contracts/turn\_runner\_context.ts:738](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L738) | | `refreshStandingInstructions` | `readonly` | () => | (`string` | [`Tokenizable`](../../common/classes/Tokenizable.md))\[] | `Promise`<(`string` | [`Tokenizable`](../../common/classes/Tokenizable.md))\[]> | Refreshes and returns the standing instructions; delegates to the callback supplied at construction. | [lib/contracts/turn\_runner\_context.ts:700](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L700) | | `standingInstructions` | `readonly` | `Set`<[`Tokenizable`](../../common/classes/Tokenizable.md)> | Standing instructions applied to every turn, in insertion order. | [lib/contracts/turn\_runner\_context.ts:678](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L678) | | `stash` | `readonly` | [`Registry`](../../common/classes/Registry.md) | Arbitrary key-value store that middleware can read and write across pipeline steps. | [lib/contracts/turn\_runner\_context.ts:674](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L674) | | `storeMediaBytes` | `readonly` | (`id`: `string`, `bytes`: [`ConduitBytes`](../type-aliases/ConduitBytes.md)) => | [`MediaReader`](../../common/interfaces/MediaReader.md) | `Promise`<[`MediaReader`](../../common/interfaces/MediaReader.md)> | Persists tool-generated media bytes into consumer storage and returns a [@nhtio/adk!MediaReader](../../common/interfaces/MediaReader.md). Low-level conduit — returns a value, touches no turn state; build a [@nhtio/adk!Media](../../common/classes/Media.md) from the reader and persist the owning primitive separately. | [lib/contracts/turn\_runner\_context.ts:746](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L746) | | `storeMemory` | `readonly` | (`v`: [`Memory`](../../common/classes/Memory.md)) => `void` | `Promise`<`void`> | Stores a new memory in the persistence layer. | [lib/contracts/turn\_runner\_context.ts:710](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L710) | | `storeMessage` | `readonly` | (`v`: [`Message`](../../common/classes/Message.md)) => `void` | `Promise`<`void`> | Stores a new message in the persistence layer. | [lib/contracts/turn\_runner\_context.ts:724](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L724) | | `storeRetrievable` | `readonly` | (`v`: [`Retrievable`](../../common/classes/Retrievable.md)) => `void` | `Promise`<`void`> | Stores a new retrievable record in the persistence layer. | [lib/contracts/turn\_runner\_context.ts:718](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L718) | | `storeRetrievableBytes` | `readonly` | (`id`: `string`, `bytes`: [`ConduitBytes`](../type-aliases/ConduitBytes.md)) => | [`SpoolReader`](../../spooled_artifact/interfaces/SpoolReader.md) | `Promise`<[`SpoolReader`](../../spooled_artifact/interfaces/SpoolReader.md)> | Persists extracted retrievable text bytes into consumer storage and returns a [@nhtio/adk!SpoolReader](../../spooled_artifact/interfaces/SpoolReader.md). Wrap it in a [@nhtio/adk!SpooledArtifact](../../spooled_artifact/classes/SpooledArtifact.md) for `Retrievable.content` and persist the record via [TurnContext.storeRetrievable](#property-storeretrievable) separately. | [lib/contracts/turn\_runner\_context.ts:755](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L755) | | `storeStandingInstruction` | `readonly` | (`v`: `string` | [`Tokenizable`](../../common/classes/Tokenizable.md)) => `void` | `Promise`<`void`> | Stores a new standing instruction in the persistence layer. | [lib/contracts/turn\_runner\_context.ts:704](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L704) | | `storeThought` | `readonly` | (`v`: [`Thought`](../../common/classes/Thought.md)) => `void` | `Promise`<`void`> | Stores a new thought in the persistence layer. | [lib/contracts/turn\_runner\_context.ts:730](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L730) | | `storeToolCall` | `readonly` | (`v`: [`ToolCall`](../../forge/classes/ToolCall.md)) => `void` | `Promise`<`void`> | Stores a new tool call in the persistence layer. | [lib/contracts/turn\_runner\_context.ts:736](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L736) | | `systemPrompt` | `readonly` | [`Tokenizable`](../../common/classes/Tokenizable.md) | The system prompt guiding the agent's behaviour for this turn. | [lib/contracts/turn\_runner\_context.ts:676](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L676) | | `tools` | `readonly` | [`ToolRegistry`](../../forge/classes/ToolRegistry.md) | Turn-scoped tool registry constructed from the runner's baseline tools; middleware may trim or extend it. | [lib/contracts/turn\_runner\_context.ts:772](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L772) | | `turnMemories` | `readonly` | `Set`<[`Memory`](../../common/classes/Memory.md)> | Memories loaded for this turn; populated by middleware after calling `fetchMemories()`. | [lib/contracts/turn\_runner\_context.ts:680](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L680) | | `turnMessages` | `readonly` | `Set`<[`Message`](../../common/classes/Message.md)> | Conversation messages loaded for this turn; populated by middleware after calling `fetchMessages()`. | [lib/contracts/turn\_runner\_context.ts:684](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L684) | | `turnRetrievables` | `readonly` | `Set`<[`Retrievable`](../../common/classes/Retrievable.md)> | Retrievable records loaded for this turn; populated by middleware after calling `fetchRetrievables()`. | [lib/contracts/turn\_runner\_context.ts:682](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L682) | | `turnThoughts` | `readonly` | `Set`<[`Thought`](../../common/classes/Thought.md)> | Thought traces loaded for this turn; populated by middleware after calling `fetchThoughts()`. | [lib/contracts/turn\_runner\_context.ts:686](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L686) | | `turnToolCalls` | `readonly` | `Set`<[`ToolCall`](../../forge/classes/ToolCall.md)> | Tool call records loaded for this turn; populated by middleware after calling `fetchToolCalls()`. | [lib/contracts/turn\_runner\_context.ts:688](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L688) | | `waitFor` | `readonly` | [`OpenGateFn`](../../turn_runner/type-aliases/OpenGateFn.md) | Opens a turn gate and suspends until it resolves, rejects, times out, or is aborted. | [lib/contracts/turn\_runner\_context.ts:770](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/turn_runner_context.ts#L770) |