Interface: DispatchContext
Defined in: src/lib/contracts/dispatch_context.ts:339
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 | Defined in |
|---|---|---|---|---|
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. | src/lib/contracts/dispatch_context.ts:1202 |
aborted | readonly | boolean | true when the abort controller signal has fired. | src/lib/contracts/dispatch_context.ts:1194 |
abortSignal | readonly | AbortSignal | The AbortSignal from the execution's AbortController. | src/lib/contracts/dispatch_context.ts:1196 |
deleteMemory | readonly | (id: string) => Promise<void> | Removes a memory from the local Set and persistence layer by ID. | src/lib/contracts/dispatch_context.ts:1254 |
deleteMessage | readonly | (id: string) => Promise<void> | Removes a message from the local Set and persistence layer by ID. | src/lib/contracts/dispatch_context.ts:1266 |
deleteRetrievable | readonly | (id: string) => Promise<void> | Removes a retrievable record from the local Set and persistence layer by ID. | src/lib/contracts/dispatch_context.ts:1260 |
deleteStandingInstruction | readonly | (v: string | Tokenizable) => Promise<void> | Removes a standing instruction from the local Set and persistence layer. | src/lib/contracts/dispatch_context.ts:1248 |
deleteThought | readonly | (id: string) => Promise<void> | Removes a thought from the local Set and persistence layer by ID. | src/lib/contracts/dispatch_context.ts:1272 |
deleteToolCall | readonly | (id: string) => Promise<void> | Removes a tool call from the local Set and persistence layer by ID. | src/lib/contracts/dispatch_context.ts:1278 |
dispatchId | readonly | string | Stable identifier for the dispatch this context belongs to; set by DispatchRunner. | src/lib/contracts/dispatch_context.ts:1190 |
emitMessage | readonly | EmitMessageFn | Emits a message hook; fires registered handlers synchronously. | src/lib/contracts/dispatch_context.ts:1313 |
emitThought | readonly | EmitThoughtFn | Emits a thought hook; fires registered handlers synchronously. | src/lib/contracts/dispatch_context.ts:1315 |
emitToolCall | readonly | EmitToolCallFn | Emits a toolCall hook; fires registered handlers synchronously. | src/lib/contracts/dispatch_context.ts:1317 |
emitToolExecutionEnd | readonly | EmitToolExecutionEndFn | Emits a toolExecutionEnd hook; fires registered handlers synchronously. | src/lib/contracts/dispatch_context.ts:1321 |
emitToolExecutionStart | readonly | EmitToolExecutionStartFn | Emits a toolExecutionStart hook; fires registered handlers synchronously. | src/lib/contracts/dispatch_context.ts:1319 |
fetchMemories | readonly | () => | Memory[] | Promise<Memory[]> | Fetches memories; delegates to the callback supplied at construction. | src/lib/contracts/dispatch_context.ts:1228 |
fetchMessages | readonly | () => | Message[] | Promise<Message[]> | Fetches messages; delegates to the callback supplied at construction. | src/lib/contracts/dispatch_context.ts:1232 |
fetchRetrievables | readonly | () => | Retrievable[] | Promise<Retrievable[]> | Fetches retrievable records; delegates to the callback supplied at construction. | src/lib/contracts/dispatch_context.ts:1230 |
fetchThoughts | readonly | () => | Thought[] | Promise<Thought[]> | Fetches thoughts; delegates to the callback supplied at construction. | src/lib/contracts/dispatch_context.ts:1234 |
fetchToolCalls | readonly | () => | ToolCall[] | Promise<ToolCall[]> | Fetches tool calls; delegates to the callback supplied at construction. | src/lib/contracts/dispatch_context.ts:1236 |
fetchTools | readonly | () => | Tool<SpooledArtifact>[] | Promise<Tool<SpooledArtifact>[]> | Fetches tools; delegates to the callback supplied at construction. | src/lib/contracts/dispatch_context.ts:1238 |
id | readonly | string | Unique identifier for this execution context, generated as UUIDv6 at construction time. | src/lib/contracts/dispatch_context.ts:1188 |
isAcked | readonly | boolean | true when the context was signalled via DispatchContext.ack. | src/lib/contracts/dispatch_context.ts:1206 |
isSignalled | readonly | boolean | true once DispatchContext.ack or DispatchContext.nack has been called. | src/lib/contracts/dispatch_context.ts:1204 |
iteration | readonly | number | 0-based iteration count within the current dispatch; updated by DispatchRunner. | src/lib/contracts/dispatch_context.ts:1192 |
mutateMemory | readonly | (v: Memory) => Promise<void> | Updates an existing memory in the local Set and persistence layer. | src/lib/contracts/dispatch_context.ts:1252 |
mutateMessage | readonly | (v: Message) => Promise<void> | Updates an existing message in the local Set and persistence layer. | src/lib/contracts/dispatch_context.ts:1264 |
mutateRetrievable | readonly | (v: Retrievable) => Promise<Retrievable> | Updates an existing retrievable record in the local Set and persistence layer. | src/lib/contracts/dispatch_context.ts:1258 |
mutateStandingInstruction | readonly | (v: string | Tokenizable) => Promise<void> | Updates an existing standing instruction in the local Set and persistence layer. | src/lib/contracts/dispatch_context.ts:1246 |
mutateThought | readonly | (v: Thought) => Promise<void> | Updates an existing thought in the local Set and persistence layer. | src/lib/contracts/dispatch_context.ts:1270 |
mutateToolCall | readonly | (v: ToolCall) => Promise<void> | Updates an existing tool call in the local Set and persistence layer. | src/lib/contracts/dispatch_context.ts:1276 |
nackError | readonly | Error | undefined | The error stored by DispatchContext.nack, or undefined if not nacked. | src/lib/contracts/dispatch_context.ts:1208 |
refreshStandingInstructions | readonly | () => | (string | Tokenizable)[] | Promise<(string | Tokenizable)[]> | Refreshes and returns standing instructions. | src/lib/contracts/dispatch_context.ts:1240 |
replaceToolCallGroup | readonly | (ids: readonly string[], replacements: readonly ToolCall[]) => Promise<void> | Replaces a complete colliding tool-call group and persists the replacement. | src/lib/contracts/dispatch_context.ts:1280 |
standingInstructions | readonly | Set<Tokenizable> | Standing instructions for this execution, in insertion order. | src/lib/contracts/dispatch_context.ts:1214 |
stash | readonly | Registry | Arbitrary key-value store for cross-step state. | src/lib/contracts/dispatch_context.ts:1210 |
storeMediaBytes | readonly | (id: string, bytes: ConduitBytes) => | MediaReader | Promise<MediaReader> | Persists tool-generated media bytes into consumer storage and returns a @nhtio/adk!MediaReader. Remarks This is a low-level persistence conduit, NOT a mutation: it does not add to turnMessages/ turnToolCalls or fire a stored* hook. The handler builds a @nhtio/adk!Media from the returned reader (Media.toolGenerated({ reader })) and stores the owning primitive — a @nhtio/adk!Message attachment or @nhtio/adk!ToolCall result — via the relevant store* method separately. Persisting bytes without storing the primitive means the framework never sees the media. | src/lib/contracts/dispatch_context.ts:1295 |
storeMemory | readonly | (v: Memory) => Promise<void> | Stores a new memory in the local Set and persistence layer. | src/lib/contracts/dispatch_context.ts:1250 |
storeMessage | readonly | (v: Message) => Promise<void> | Stores a new message in the local Set and persistence layer. | src/lib/contracts/dispatch_context.ts:1262 |
storeRetrievable | readonly | (v: Retrievable) => Promise<Retrievable> | Stores a new retrievable record in the local Set and persistence layer. | src/lib/contracts/dispatch_context.ts:1256 |
storeRetrievableBytes | readonly | (id: string, bytes: ConduitBytes) => | SpoolReader | Promise<SpoolReader> | Persists extracted retrievable text bytes into consumer storage and returns a @nhtio/adk!SpoolReader. Remarks Low-level persistence conduit, same posture as DispatchContext.storeMediaBytes: returns a value, touches no Sets, fires no hook. Wrap the reader in a @nhtio/adk!SpooledArtifact and pass it as Retrievable.content, then persist the record via DispatchContext.storeRetrievable. | src/lib/contracts/dispatch_context.ts:1308 |
storeStandingInstruction | readonly | (v: string | Tokenizable) => Promise<void> | Stores a new standing instruction in the local Set and persistence layer. | src/lib/contracts/dispatch_context.ts:1244 |
storeThought | readonly | (v: Thought) => Promise<void> | Stores a new thought in the local Set and persistence layer. | src/lib/contracts/dispatch_context.ts:1268 |
storeToolCall | readonly | (v: ToolCall) => Promise<void> | Stores a new tool call in the local Set and persistence layer. | src/lib/contracts/dispatch_context.ts:1274 |
systemPrompt | readonly | Tokenizable | The system prompt for this execution. | src/lib/contracts/dispatch_context.ts:1212 |
tools | readonly | ToolRegistry | Tool registry for this execution. | src/lib/contracts/dispatch_context.ts:1226 |
turnMemories | readonly | Set<Memory> | Memories loaded for this execution. | src/lib/contracts/dispatch_context.ts:1216 |
turnMessages | readonly | Set<Message> | Messages loaded for this execution. | src/lib/contracts/dispatch_context.ts:1220 |
turnRetrievables | readonly | Set<Retrievable> | Retrievable records loaded for this execution. | src/lib/contracts/dispatch_context.ts:1218 |
turnThoughts | readonly | Set<Thought> | Thoughts loaded for this execution. | src/lib/contracts/dispatch_context.ts:1222 |
turnToolCalls | readonly | Set<ToolCall> | Tool calls loaded for this execution. | src/lib/contracts/dispatch_context.ts:1224 |
waitFor | readonly | OpenGateFn | Opens a gate and suspends until it resolves, rejects, times out, or is aborted. | src/lib/contracts/dispatch_context.ts:1323 |
Methods
ack()
ack(): void;Defined in: src/lib/contracts/dispatch_context.ts:1104
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;Defined in: src/lib/contracts/dispatch_context.ts:1162
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;Defined in: src/lib/contracts/dispatch_context.ts:1143
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
toolCallCount()
toolCallCount(checksum: string): number;Defined in: src/lib/contracts/dispatch_context.ts:1089
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.