Interface: DispatchContext

Context object for a single LLM execution call.

Remarks

Mirrors the surface of @nhtio/adk!TurnContext but is path-agnostic — it knows nothing about a parent context. Mutations apply to local Sets immediately, call persistence callbacks immediately, and fire the corresponding mutation hook (storedMemory, mutatedMemory, deletedMemory, etc.) in both standalone and derived dispatches.

The @nhtio/adk!DispatchRunner is the only thing that creates a context with a parent relationship: when dispatched with a source: TurnContext, the runner subscribes to the mutation hooks, queues deltas internally, and flushes them to the parent's Sets at the end of each iteration. The context itself remains unaware of the parent.

Middleware/executor signals termination via DispatchContext.ack (clean completion) or DispatchContext.nack (failure). Both set an internal flag the runner reads at end-of-iteration to decide whether to loop or exit. DispatchContext.isSignalled, DispatchContext.isAcked, and DispatchContext.nackError are publicly readable getters so middleware can inspect signal state and bail early.

Properties

Property	Modifier	Type	Description
abort	readonly	(reason?: unknown) => void	Aborts the dispatch's AbortController with the supplied reason. Middleware should call this when refusing to proceed — the runner short-circuits cleanly, dispatchEnd.status resolves to 'aborted', and no error event is emitted.
aborted	readonly	boolean	true when the abort controller signal has fired.
abortSignal	readonly	AbortSignal	The AbortSignal from the execution's AbortController.
deleteMemory	readonly	(id: string) => Promise<void>	Removes a memory from the local Set and persistence layer by ID.
deleteMessage	readonly	(id: string) => Promise<void>	Removes a message from the local Set and persistence layer by ID.
deleteRetrievable	readonly	(id: string) => Promise<void>	Removes a retrievable record from the local Set and persistence layer by ID.
deleteStandingInstruction	readonly	(v: string | Tokenizable) => Promise<void>	Removes a standing instruction from the local Set and persistence layer.
deleteThought	readonly	(id: string) => Promise<void>	Removes a thought from the local Set and persistence layer by ID.
deleteToolCall	readonly	(id: string) => Promise<void>	Removes a tool call from the local Set and persistence layer by ID.
dispatchId	readonly	string	Stable identifier for the dispatch this context belongs to; set by DispatchRunner.
emitMessage	readonly	EmitMessageFn	Emits a message hook; fires registered handlers synchronously.
emitThought	readonly	EmitThoughtFn	Emits a thought hook; fires registered handlers synchronously.
emitToolCall	readonly	EmitToolCallFn	Emits a toolCall hook; fires registered handlers synchronously.
emitToolExecutionEnd	readonly	EmitToolExecutionEndFn	Emits a toolExecutionEnd hook; fires registered handlers synchronously.
emitToolExecutionStart	readonly	EmitToolExecutionStartFn	Emits a toolExecutionStart hook; fires registered handlers synchronously.
fetchMemories	readonly	() => | Memory[] | Promise<Memory[]>	Fetches memories; delegates to the callback supplied at construction.
fetchMessages	readonly	() => | Message[] | Promise<Message[]>	Fetches messages; delegates to the callback supplied at construction.
fetchRetrievables	readonly	() => | Retrievable[] | Promise<Retrievable[]>	Fetches retrievable records; delegates to the callback supplied at construction.
fetchThoughts	readonly	() => | Thought[] | Promise<Thought[]>	Fetches thoughts; delegates to the callback supplied at construction.
fetchToolCalls	readonly	() => | ToolCall[] | Promise<ToolCall[]>	Fetches tool calls; delegates to the callback supplied at construction.
fetchTools	readonly	() => | Tool<SpooledArtifact>[] | Promise<Tool<SpooledArtifact>[]>	Fetches tools; delegates to the callback supplied at construction.
id	readonly	string	Unique identifier for this execution context, generated as UUIDv6 at construction time.
isAcked	readonly	boolean	true when the context was signalled via DispatchContext.ack.
isSignalled	readonly	boolean	true once DispatchContext.ack or DispatchContext.nack has been called.
iteration	readonly	number	0-based iteration count within the current dispatch; updated by DispatchRunner.
mutateMemory	readonly	(v: Memory) => Promise<void>	Updates an existing memory in the local Set and persistence layer.
mutateMessage	readonly	(v: Message) => Promise<void>	Updates an existing message in the local Set and persistence layer.
mutateRetrievable	readonly	(v: Retrievable) => Promise<void>	Updates an existing retrievable record in the local Set and persistence layer.
mutateStandingInstruction	readonly	(v: string | Tokenizable) => Promise<void>	Updates an existing standing instruction in the local Set and persistence layer.
mutateThought	readonly	(v: Thought) => Promise<void>	Updates an existing thought in the local Set and persistence layer.
mutateToolCall	readonly	(v: ToolCall) => Promise<void>	Updates an existing tool call in the local Set and persistence layer.
nackError	readonly	Error | undefined	The error stored by DispatchContext.nack, or undefined if not nacked.
refreshStandingInstructions	readonly	() => | (string | Tokenizable)[] | Promise<(string | Tokenizable)[]>	Refreshes and returns standing instructions.
standingInstructions	readonly	Set<Tokenizable>	Standing instructions for this execution, in insertion order.
stash	readonly	Registry	Arbitrary key-value store for cross-step state.
storeMemory	readonly	(v: Memory) => Promise<void>	Stores a new memory in the local Set and persistence layer.
storeMessage	readonly	(v: Message) => Promise<void>	Stores a new message in the local Set and persistence layer.
storeRetrievable	readonly	(v: Retrievable) => Promise<void>	Stores a new retrievable record in the local Set and persistence layer.
storeStandingInstruction	readonly	(v: string | Tokenizable) => Promise<void>	Stores a new standing instruction in the local Set and persistence layer.
storeThought	readonly	(v: Thought) => Promise<void>	Stores a new thought in the local Set and persistence layer.
storeToolCall	readonly	(v: ToolCall) => Promise<void>	Stores a new tool call in the local Set and persistence layer.
systemPrompt	readonly	Tokenizable	The system prompt for this execution.
tools	readonly	ToolRegistry	Tool registry for this execution.
turnMemories	readonly	Set<Memory>	Memories loaded for this execution.
turnMessages	readonly	Set<Message>	Messages loaded for this execution.
turnRetrievables	readonly	Set<Retrievable>	Retrievable records loaded for this execution.
turnThoughts	readonly	Set<Thought>	Thoughts loaded for this execution.
turnToolCalls	readonly	Set<ToolCall>	Tool calls loaded for this execution.
waitFor	readonly	OpenGateFn	Opens a gate and suspends until it resolves, rejects, times out, or is aborted.

Methods

_getHooks()

_getHooks(): Hooks<DispatchContextHooks>;

Internal

Accessor used by @nhtio/adk!DispatchRunner to register forwarding handlers.

Returns

Hooks<DispatchContextHooks>

---

_setDispatchId()

_setDispatchId(id: string): void;

Internal

Set by @nhtio/adk!DispatchRunner after construction.

Parameters

Parameter	Type
id	string

Returns

void

---

_setIteration()

_setIteration(n: number): void;

Internal

Updated by @nhtio/adk!DispatchRunner on each iteration.

Parameters

Parameter	Type
n	number

Returns

void

---

ack()

ack(): void;

Signals successful completion of this execution.

Returns

void

Remarks

Sets the context's internal signal flag. The @nhtio/adk!DispatchRunner reads the flag at the end of each iteration to decide whether to loop or exit. Calling ack() does NOT abort the current iteration — the current pipeline and flush complete first.

Throws

@nhtio/adk!E_LLM_EXECUTION_ALREADY_SIGNALLED when the context has already been signalled (whether via ack() or nack()).

---

nack()

nack(error?: Error): void;

Signals failed completion of this execution, optionally with an error.

Parameters

Parameter	Type	Description
error?	Error	Optional error describing the failure. If omitted, a generic Error is used.

Returns

void

Remarks

Sets the context's internal signal flag and stores the error. The @nhtio/adk!DispatchRunner reads the flag at the end of each iteration and surfaces the error via the dispatchEnd observability payload and as the rejection reason of dispatch(). Calling nack() does NOT abort the current iteration — the current pipeline and flush complete first.

Throws

@nhtio/adk!E_LLM_EXECUTION_ALREADY_SIGNALLED when the context has already been signalled.

---

onAck()

onAck(handler: () => void): () => void;

Registers a handler to run when this context completes successfully via ack.

Parameters

Parameter	Type	Description
handler	() => void	Callback invoked when ack() is called.

Returns

An unsubscribe function that removes the handler.

() => void

Remarks

The handler does NOT fire on nack — failed executor runs should leave any ack-tied subscriptions alone so the consumer can inspect what was registered when debugging the failure. Returns an unsubscribe function; subscriptions are short-lived and die with the context regardless.

The canonical consumer is ToolRegistry.bindContext(ctx), which uses this hook to drop ephemeral tools (notably forged artifact-query tools from SpooledArtifact.forgeTools(ctx)) at ctx-completion. Consumers may also register custom handlers here for any per-executor cleanup.

See

• @nhtio/adk!ToolRegistry.bindContext
• @nhtio/adk!SpooledArtifact.forgeTools

---

toolCallCount()

toolCallCount(checksum: string): number;

Returns how many times a tool call with the given checksum has been stored in this execution.

Parameters

Parameter	Type	Description
checksum	string	The ToolCall.checksum value to look up.

Returns

number

Remarks

Checksums are computed over tool + args (see @nhtio/adk!ToolCall.checksum). This count lets the executor detect repeat invocations of the same call without scanning the full Set. Returns 0 when the checksum has not been seen.