@nhtio/adk 0.1.0-master-f0aa531d

package/dispatch_runner-9j6bXHL3.mjs

@@ -0,0 +1,1609 @@
+import { a as validateOrThrow } from "./exceptions-NrzIHw_R.mjs";
+import { a as Tokenizable, n as canonicalStringify, o as isError, r as Registry, s as isInstanceOf, t as ToolRegistry } from "./tool_registry-DqLOyGyG.mjs";
+import { T as E_PIPELINE_SHORT_CIRCUITED, b as E_LLM_EXECUTION_EXECUTOR_ERROR, g as E_INVALID_TURN_CONTEXT, m as E_INVALID_LLM_EXECUTION_CONTEXT, p as E_INVALID_LLM_DISPATCH_INPUT, t as E_DISPATCH_PIPELINE_ERROR, x as E_LLM_EXECUTION_GATE_NOT_SUPPORTED, y as E_LLM_EXECUTION_ALREADY_SIGNALLED } from "./runtime-CrEPIFgr.mjs";
+import { validator } from "@nhtio/validation";
+import { v6 } from "uuid";
+import { DateTime } from "luxon";
+import { sha256 } from "js-sha256";
+import { Hooks } from "@nhtio/hooks";
+import { Middleware } from "@nhtio/middleware";
+//#region src/lib/contracts/turn_runner_context.ts
+/**
+* Validator schema used to validate a {@link RawTurnContext} before constructing a {@link TurnContext}.
+*
+* @remarks
+* Validates all four fields of {@link RawTurnContext}:
+* - `turnAbortController` — required `AbortController` instance.
+* - `stash` — optional string-keyed object; defaults to `{}`.
+* - `systemPrompt` — required string or {@link @nhtio/adk!Tokenizable}, via {@link @nhtio/adk!Tokenizable.schema}.
+* - `standingInstructions` — optional array of strings or {@link @nhtio/adk!Tokenizable} instances, each
+*   validated via {@link @nhtio/adk!Tokenizable.schema}; defaults to `[]`.
+*
+* Throws a `ValidationException` (via {@link validateOrThrow}) when validation fails.
+*/
+var turnContextSchema = validator.object({
+	turnAbortController: validator.alternatives(validator.object().instance(AbortController), validator.function().instance(AbortController)).required(),
+	stash: validator.object().pattern(validator.string(), validator.any()).default({}),
+	systemPrompt: Tokenizable.schema.required(),
+	standingInstructions: validator.array().items(Tokenizable.schema).default([])
+}).required();
+/**
+* The validated, strongly-typed context object threaded through every middleware step in a
+* single agent turn.
+*
+* @remarks
+* Constructed from a {@link RawTurnContext} by {@link @nhtio/adk!TurnRunner.run}. Middleware functions
+* receive this object and use it to read and share state across pipeline steps.
+*/
+var TurnContext = class TurnContext {
+	/**
+	* Returns `true` if `value` is a {@link TurnContext} instance.
+	*
+	* @remarks
+	* Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety. The ADK does not export the
+	* `TurnContext` class itself as a constructable value — use this guard plus the
+	* {@link TurnContext} type for runtime detection and TypeScript narrowing.
+	*
+	* @param value - The value to test.
+	* @returns `true` when `value` is a {@link TurnContext} instance.
+	*/
+	static isTurnContext(value) {
+		return isInstanceOf(value, "TurnContext", TurnContext);
+	}
+	#id;
+	#turnAbortController;
+	#stash;
+	#systemPrompt;
+	#standingInstructions;
+	#turnMemories;
+	#turnRetrievables;
+	#turnMessages;
+	#turnThoughts;
+	#turnToolCalls;
+	/**
+	* @param raw - The raw context input validated against {@link turnContextSchema}.
+	* @param injected - Runtime callbacks supplied by `TurnRunner`; bound as instance methods so
+	*   middleware can call fetch and emit methods directly on the context.
+	* @throws {@link @nhtio/adk!E_INVALID_TURN_CONTEXT} when `raw` does not satisfy the schema.
+	*
+	* @internal
+	*/
+	constructor(raw, injected) {
+		try {
+			raw = validateOrThrow(turnContextSchema, raw, true);
+		} catch (err) {
+			throw new E_INVALID_TURN_CONTEXT({ cause: isError(err) ? err : void 0 });
+		}
+		this.#id = v6();
+		this.#turnAbortController = raw.turnAbortController;
+		this.#stash = new Registry(raw.stash);
+		this.#systemPrompt = Tokenizable.isTokenizable(raw.systemPrompt) ? raw.systemPrompt : new Tokenizable(raw.systemPrompt);
+		this.#standingInstructions = new Set((raw.standingInstructions || []).map((instr) => Tokenizable.isTokenizable(instr) ? instr : new Tokenizable(instr)));
+		this.#turnMemories = /* @__PURE__ */ new Set();
+		this.#turnRetrievables = /* @__PURE__ */ new Set();
+		this.#turnMessages = /* @__PURE__ */ new Set();
+		this.#turnThoughts = /* @__PURE__ */ new Set();
+		this.#turnToolCalls = /* @__PURE__ */ new Set();
+		Object.defineProperties(this, {
+			id: {
+				get: () => this.#id,
+				enumerable: true,
+				configurable: false
+			},
+			aborted: {
+				get: () => Boolean(this.#turnAbortController.signal.aborted),
+				enumerable: true,
+				configurable: false
+			},
+			abortSignal: {
+				get: () => this.#turnAbortController.signal,
+				enumerable: true,
+				configurable: false
+			},
+			abort: {
+				value: (reason) => this.#turnAbortController.abort(reason),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			stash: {
+				get: () => this.#stash,
+				enumerable: true,
+				configurable: false
+			},
+			systemPrompt: {
+				get: () => this.#systemPrompt,
+				enumerable: true,
+				configurable: false
+			},
+			standingInstructions: {
+				get: () => this.#standingInstructions,
+				enumerable: true,
+				configurable: false
+			},
+			turnMemories: {
+				get: () => this.#turnMemories,
+				enumerable: true,
+				configurable: false
+			},
+			turnRetrievables: {
+				get: () => this.#turnRetrievables,
+				enumerable: true,
+				configurable: false
+			},
+			turnMessages: {
+				get: () => this.#turnMessages,
+				enumerable: true,
+				configurable: false
+			},
+			turnThoughts: {
+				get: () => this.#turnThoughts,
+				enumerable: true,
+				configurable: false
+			},
+			turnToolCalls: {
+				get: () => this.#turnToolCalls,
+				enumerable: true,
+				configurable: false
+			}
+		});
+		Object.defineProperties(this, {
+			fetchMemories: {
+				value: () => injected.fetchMemories(this),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			fetchMessages: {
+				value: () => injected.fetchMessages(this),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			fetchThoughts: {
+				value: () => injected.fetchThoughts(this),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			fetchToolCalls: {
+				value: () => injected.fetchToolCalls(this),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			fetchTools: {
+				value: () => injected.fetchTools(this),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			refreshStandingInstructions: {
+				value: () => injected.refreshStandingInstructions(this),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			storeStandingInstruction: {
+				value: (v) => injected.storeStandingInstruction(this, v),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			mutateStandingInstruction: {
+				value: (v) => injected.mutateStandingInstruction(this, v),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			deleteStandingInstruction: {
+				value: (v) => injected.deleteStandingInstruction(this, v),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			storeMemory: {
+				value: (v) => injected.storeMemory(this, v),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			mutateMemory: {
+				value: (v) => injected.mutateMemory(this, v),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			deleteMemory: {
+				value: (id) => injected.deleteMemory(this, id),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			fetchRetrievables: {
+				value: () => injected.fetchRetrievables(this),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			storeRetrievable: {
+				value: (v) => injected.storeRetrievable(this, v),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			mutateRetrievable: {
+				value: (v) => injected.mutateRetrievable(this, v),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			deleteRetrievable: {
+				value: (id) => injected.deleteRetrievable(this, id),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			storeMessage: {
+				value: (v) => injected.storeMessage(this, v),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			mutateMessage: {
+				value: (v) => injected.mutateMessage(this, v),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			deleteMessage: {
+				value: (id) => injected.deleteMessage(this, id),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			storeThought: {
+				value: (v) => injected.storeThought(this, v),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			mutateThought: {
+				value: (v) => injected.mutateThought(this, v),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			deleteThought: {
+				value: (id) => injected.deleteThought(this, id),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			storeToolCall: {
+				value: (v) => injected.storeToolCall(this, v),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			mutateToolCall: {
+				value: (v) => injected.mutateToolCall(this, v),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			deleteToolCall: {
+				value: (id) => injected.deleteToolCall(this, id),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			emitMessage: {
+				value: injected.emitMessage,
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			emitThought: {
+				value: injected.emitThought,
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			emitToolCall: {
+				value: injected.emitToolCall,
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			emitToolExecutionStart: {
+				value: injected.emitToolExecutionStart,
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			emitToolExecutionEnd: {
+				value: injected.emitToolExecutionEnd,
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			waitFor: {
+				value: injected.openGate,
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			tools: {
+				get: () => injected.tools,
+				enumerable: true,
+				configurable: false
+			}
+		});
+	}
+};
+//#endregion
+//#region src/lib/contracts/dispatch_context.ts
+var rawDispatchContextSchema = validator.object({
+	turnAbortController: validator.alternatives(validator.object().instance(AbortController), validator.function().instance(AbortController)).optional(),
+	stash: validator.object().pattern(validator.string(), validator.any()).default({}),
+	systemPrompt: Tokenizable.schema.required(),
+	standingInstructions: validator.array().items(Tokenizable.schema).default([]),
+	memories: validator.array().default([]),
+	retrievables: validator.array().default([]),
+	messages: validator.array().default([]),
+	thoughts: validator.array().default([]),
+	toolCalls: validator.array().default([]),
+	tools: validator.array().default([]),
+	fetchMemories: validator.function().required(),
+	fetchRetrievables: validator.function().required(),
+	fetchMessages: validator.function().required(),
+	fetchThoughts: validator.function().required(),
+	fetchToolCalls: validator.function().required(),
+	fetchTools: validator.function().required(),
+	refreshStandingInstructions: validator.function().required(),
+	storeStandingInstruction: validator.function().required(),
+	mutateStandingInstruction: validator.function().required(),
+	deleteStandingInstruction: validator.function().required(),
+	storeMemory: validator.function().required(),
+	mutateMemory: validator.function().required(),
+	deleteMemory: validator.function().required(),
+	storeRetrievable: validator.function().required(),
+	mutateRetrievable: validator.function().required(),
+	deleteRetrievable: validator.function().required(),
+	storeMessage: validator.function().required(),
+	mutateMessage: validator.function().required(),
+	deleteMessage: validator.function().required(),
+	storeThought: validator.function().required(),
+	mutateThought: validator.function().required(),
+	deleteThought: validator.function().required(),
+	storeToolCall: validator.function().required(),
+	mutateToolCall: validator.function().required(),
+	deleteToolCall: validator.function().required(),
+	hooks: validator.object().optional(),
+	waitFor: validator.function().optional()
+});
+/**
+* Context object for a single LLM execution call.
+*
+* @remarks
+* Mirrors the surface of {@link @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 {@link @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 {@link DispatchContext.ack} (clean completion)
+* or {@link DispatchContext.nack} (failure). Both set an internal flag the runner reads at
+* end-of-iteration to decide whether to loop or exit. {@link DispatchContext.isSignalled},
+* {@link DispatchContext.isAcked}, and {@link DispatchContext.nackError} are publicly
+* readable getters so middleware can inspect signal state and bail early.
+*/
+var DispatchContext = class DispatchContext {
+	#id;
+	#dispatchId;
+	#iteration;
+	#turnAbortController;
+	#stash;
+	#systemPrompt;
+	#standingInstructions;
+	#turnMemories;
+	#turnRetrievables;
+	#turnMessages;
+	#turnThoughts;
+	#turnToolCalls;
+	#tools;
+	#hooks;
+	#ackHandlers;
+	#fetchMemories;
+	#fetchRetrievables;
+	#fetchMessages;
+	#fetchThoughts;
+	#fetchToolCalls;
+	#fetchTools;
+	#refreshStandingInstructions;
+	#storeStandingInstruction;
+	#mutateStandingInstruction;
+	#deleteStandingInstruction;
+	#storeMemory;
+	#mutateMemory;
+	#deleteMemory;
+	#storeRetrievable;
+	#mutateRetrievable;
+	#deleteRetrievable;
+	#storeMessage;
+	#mutateMessage;
+	#deleteMessage;
+	#storeThought;
+	#mutateThought;
+	#deleteThought;
+	#storeToolCall;
+	#mutateToolCall;
+	#deleteToolCall;
+	#waitFor;
+	#toolCallChecksums;
+	#signalled;
+	#nackError;
+	/**
+	* @param raw - Raw input validated against the schema.
+	* @throws {@link @nhtio/adk!E_INVALID_LLM_EXECUTION_CONTEXT} when `raw` does not satisfy the schema.
+	*/
+	constructor(raw) {
+		let resolved;
+		try {
+			resolved = validateOrThrow(rawDispatchContextSchema, raw, true);
+		} catch (err) {
+			throw new E_INVALID_LLM_EXECUTION_CONTEXT({ cause: isError(err) ? err : void 0 });
+		}
+		this.#id = v6();
+		this.#dispatchId = "";
+		this.#iteration = 0;
+		this.#turnAbortController = resolved.turnAbortController ?? new AbortController();
+		this.#stash = new Registry(resolved.stash);
+		this.#systemPrompt = Tokenizable.isTokenizable(resolved.systemPrompt) ? resolved.systemPrompt : new Tokenizable(resolved.systemPrompt);
+		this.#standingInstructions = new Set(resolved.standingInstructions.map((i) => Tokenizable.isTokenizable(i) ? i : new Tokenizable(i)));
+		this.#turnMemories = new Set(resolved.memories);
+		this.#turnRetrievables = new Set(resolved.retrievables);
+		this.#turnMessages = new Set(resolved.messages);
+		this.#turnThoughts = new Set(resolved.thoughts);
+		this.#turnToolCalls = new Set(resolved.toolCalls);
+		this.#tools = new ToolRegistry(resolved.tools);
+		this.#toolCallChecksums = /* @__PURE__ */ new Map();
+		for (const tc of resolved.toolCalls) {
+			const prev = this.#toolCallChecksums.get(tc.checksum) ?? 0;
+			this.#toolCallChecksums.set(tc.checksum, prev + 1);
+		}
+		this.#fetchMemories = resolved.fetchMemories;
+		this.#fetchRetrievables = resolved.fetchRetrievables;
+		this.#fetchMessages = resolved.fetchMessages;
+		this.#fetchThoughts = resolved.fetchThoughts;
+		this.#fetchToolCalls = resolved.fetchToolCalls;
+		this.#fetchTools = resolved.fetchTools;
+		this.#refreshStandingInstructions = resolved.refreshStandingInstructions;
+		this.#storeStandingInstruction = resolved.storeStandingInstruction;
+		this.#mutateStandingInstruction = resolved.mutateStandingInstruction;
+		this.#deleteStandingInstruction = resolved.deleteStandingInstruction;
+		this.#storeMemory = resolved.storeMemory;
+		this.#mutateMemory = resolved.mutateMemory;
+		this.#deleteMemory = resolved.deleteMemory;
+		this.#storeRetrievable = resolved.storeRetrievable;
+		this.#mutateRetrievable = resolved.mutateRetrievable;
+		this.#deleteRetrievable = resolved.deleteRetrievable;
+		this.#storeMessage = resolved.storeMessage;
+		this.#mutateMessage = resolved.mutateMessage;
+		this.#deleteMessage = resolved.deleteMessage;
+		this.#storeThought = resolved.storeThought;
+		this.#mutateThought = resolved.mutateThought;
+		this.#deleteThought = resolved.deleteThought;
+		this.#storeToolCall = resolved.storeToolCall;
+		this.#mutateToolCall = resolved.mutateToolCall;
+		this.#deleteToolCall = resolved.deleteToolCall;
+		this.#waitFor = resolved.waitFor;
+		this.#signalled = void 0;
+		this.#nackError = void 0;
+		this.#hooks = new Hooks();
+		this.#ackHandlers = /* @__PURE__ */ new Set();
+		if (resolved.hooks) {
+			const regs = resolved.hooks;
+			for (const key of Object.keys(regs)) {
+				const entry = regs[key];
+				if (!entry) continue;
+				const handlers = Array.isArray(entry) ? entry : [entry];
+				for (const h of handlers) this.#hooks.add(key, h);
+			}
+		}
+		Object.defineProperties(this, {
+			id: {
+				get: () => this.#id,
+				enumerable: true,
+				configurable: false
+			},
+			dispatchId: {
+				get: () => this.#dispatchId,
+				enumerable: true,
+				configurable: false
+			},
+			iteration: {
+				get: () => this.#iteration,
+				enumerable: true,
+				configurable: false
+			},
+			aborted: {
+				get: () => Boolean(this.#turnAbortController.signal.aborted),
+				enumerable: true,
+				configurable: false
+			},
+			abortSignal: {
+				get: () => this.#turnAbortController.signal,
+				enumerable: true,
+				configurable: false
+			},
+			abort: {
+				value: (reason) => this.#turnAbortController.abort(reason),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			isSignalled: {
+				get: () => this.#signalled !== void 0,
+				enumerable: true,
+				configurable: false
+			},
+			isAcked: {
+				get: () => this.#signalled === "ack",
+				enumerable: true,
+				configurable: false
+			},
+			nackError: {
+				get: () => this.#nackError,
+				enumerable: true,
+				configurable: false
+			},
+			stash: {
+				get: () => this.#stash,
+				enumerable: true,
+				configurable: false
+			},
+			systemPrompt: {
+				get: () => this.#systemPrompt,
+				enumerable: true,
+				configurable: false
+			},
+			standingInstructions: {
+				get: () => this.#standingInstructions,
+				enumerable: true,
+				configurable: false
+			},
+			turnMemories: {
+				get: () => this.#turnMemories,
+				enumerable: true,
+				configurable: false
+			},
+			turnRetrievables: {
+				get: () => this.#turnRetrievables,
+				enumerable: true,
+				configurable: false
+			},
+			turnMessages: {
+				get: () => this.#turnMessages,
+				enumerable: true,
+				configurable: false
+			},
+			turnThoughts: {
+				get: () => this.#turnThoughts,
+				enumerable: true,
+				configurable: false
+			},
+			turnToolCalls: {
+				get: () => this.#turnToolCalls,
+				enumerable: true,
+				configurable: false
+			},
+			tools: {
+				get: () => this.#tools,
+				enumerable: true,
+				configurable: false
+			},
+			fetchMemories: {
+				value: () => this.#fetchMemories(this),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			fetchRetrievables: {
+				value: () => this.#fetchRetrievables(this),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			fetchMessages: {
+				value: () => this.#fetchMessages(this),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			fetchThoughts: {
+				value: () => this.#fetchThoughts(this),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			fetchToolCalls: {
+				value: () => this.#fetchToolCalls(this),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			fetchTools: {
+				value: () => this.#fetchTools(this),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			refreshStandingInstructions: {
+				value: () => this.#refreshStandingInstructions(this),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			storeStandingInstruction: {
+				value: (v) => this.#doStoreStandingInstruction(v),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			mutateStandingInstruction: {
+				value: (v) => this.#doMutateStandingInstruction(v),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			deleteStandingInstruction: {
+				value: (v) => this.#doDeleteStandingInstruction(v),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			storeMemory: {
+				value: (v) => this.#doStoreMemory(v),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			mutateMemory: {
+				value: (v) => this.#doMutateMemory(v),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			deleteMemory: {
+				value: (id) => this.#doDeleteMemory(id),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			storeRetrievable: {
+				value: (v) => this.#doStoreRetrievable(v),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			mutateRetrievable: {
+				value: (v) => this.#doMutateRetrievable(v),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			deleteRetrievable: {
+				value: (id) => this.#doDeleteRetrievable(id),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			storeMessage: {
+				value: (v) => this.#doStoreMessage(v),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			mutateMessage: {
+				value: (v) => this.#doMutateMessage(v),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			deleteMessage: {
+				value: (id) => this.#doDeleteMessage(id),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			storeThought: {
+				value: (v) => this.#doStoreThought(v),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			mutateThought: {
+				value: (v) => this.#doMutateThought(v),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			deleteThought: {
+				value: (id) => this.#doDeleteThought(id),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			storeToolCall: {
+				value: (v) => this.#doStoreToolCall(v),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			mutateToolCall: {
+				value: (v) => this.#doMutateToolCall(v),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			deleteToolCall: {
+				value: (id) => this.#doDeleteToolCall(id),
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			emitMessage: {
+				value: (content) => {
+					this.#hooks.runner("message").run(content);
+				},
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			emitThought: {
+				value: (content) => {
+					this.#hooks.runner("thought").run(content);
+				},
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			emitToolCall: {
+				value: (content) => {
+					this.#hooks.runner("toolCall").run(content);
+				},
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			emitToolExecutionStart: {
+				value: (event) => {
+					this.#hooks.runner("toolExecutionStart").run(event);
+				},
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			emitToolExecutionEnd: {
+				value: (event) => {
+					this.#hooks.runner("toolExecutionEnd").run(event);
+				},
+				enumerable: true,
+				configurable: false,
+				writable: false
+			},
+			waitFor: {
+				value: (gateRaw) => {
+					if (!this.#waitFor) return Promise.reject(new E_LLM_EXECUTION_GATE_NOT_SUPPORTED());
+					return this.#waitFor(gateRaw);
+				},
+				enumerable: true,
+				configurable: false,
+				writable: false
+			}
+		});
+	}
+	async #doStoreStandingInstruction(v) {
+		const t = Tokenizable.isTokenizable(v) ? v : new Tokenizable(v);
+		this.#standingInstructions.add(t);
+		await this.#storeStandingInstruction(this, v);
+		this.#hooks.runner("storedStandingInstruction").run(t);
+	}
+	async #doMutateStandingInstruction(v) {
+		const t = Tokenizable.isTokenizable(v) ? v : new Tokenizable(v);
+		this.#standingInstructions.add(t);
+		await this.#mutateStandingInstruction(this, v);
+		this.#hooks.runner("mutatedStandingInstruction").run(t);
+	}
+	async #doDeleteStandingInstruction(v) {
+		const t = Tokenizable.isTokenizable(v) ? v : new Tokenizable(v);
+		this.#standingInstructions.delete(t);
+		await this.#deleteStandingInstruction(this, v);
+		this.#hooks.runner("deletedStandingInstruction").run(t);
+	}
+	async #doStoreMemory(v) {
+		this.#turnMemories.add(v);
+		await this.#storeMemory(this, v);
+		this.#hooks.runner("storedMemory").run(v);
+	}
+	async #doMutateMemory(v) {
+		this.#turnMemories.add(v);
+		await this.#mutateMemory(this, v);
+		this.#hooks.runner("mutatedMemory").run(v);
+	}
+	async #doDeleteMemory(id) {
+		for (const m of this.#turnMemories) if (m.id === id) {
+			this.#turnMemories.delete(m);
+			break;
+		}
+		await this.#deleteMemory(this, id);
+		this.#hooks.runner("deletedMemory").run(id);
+	}
+	async #doStoreRetrievable(v) {
+		this.#turnRetrievables.add(v);
+		await this.#storeRetrievable(this, v);
+		this.#hooks.runner("storedRetrievable").run(v);
+	}
+	async #doMutateRetrievable(v) {
+		this.#turnRetrievables.add(v);
+		await this.#mutateRetrievable(this, v);
+		this.#hooks.runner("mutatedRetrievable").run(v);
+	}
+	async #doDeleteRetrievable(id) {
+		for (const r of this.#turnRetrievables) if (r.id === id) {
+			this.#turnRetrievables.delete(r);
+			break;
+		}
+		await this.#deleteRetrievable(this, id);
+		this.#hooks.runner("deletedRetrievable").run(id);
+	}
+	async #doStoreMessage(v) {
+		this.#turnMessages.add(v);
+		await this.#storeMessage(this, v);
+		this.#hooks.runner("storedMessage").run(v);
+	}
+	async #doMutateMessage(v) {
+		this.#turnMessages.add(v);
+		await this.#mutateMessage(this, v);
+		this.#hooks.runner("mutatedMessage").run(v);
+	}
+	async #doDeleteMessage(id) {
+		for (const m of this.#turnMessages) if (m.id === id) {
+			this.#turnMessages.delete(m);
+			break;
+		}
+		await this.#deleteMessage(this, id);
+		this.#hooks.runner("deletedMessage").run(id);
+	}
+	async #doStoreThought(v) {
+		this.#turnThoughts.add(v);
+		await this.#storeThought(this, v);
+		this.#hooks.runner("storedThought").run(v);
+	}
+	async #doMutateThought(v) {
+		this.#turnThoughts.add(v);
+		await this.#mutateThought(this, v);
+		this.#hooks.runner("mutatedThought").run(v);
+	}
+	async #doDeleteThought(id) {
+		for (const t of this.#turnThoughts) if (t.id === id) {
+			this.#turnThoughts.delete(t);
+			break;
+		}
+		await this.#deleteThought(this, id);
+		this.#hooks.runner("deletedThought").run(id);
+	}
+	async #doStoreToolCall(v) {
+		this.#turnToolCalls.add(v);
+		const prev = this.#toolCallChecksums.get(v.checksum) ?? 0;
+		this.#toolCallChecksums.set(v.checksum, prev + 1);
+		await this.#storeToolCall(this, v);
+		this.#hooks.runner("storedToolCall").run(v);
+	}
+	async #doMutateToolCall(v) {
+		this.#turnToolCalls.add(v);
+		await this.#mutateToolCall(this, v);
+		this.#hooks.runner("mutatedToolCall").run(v);
+	}
+	async #doDeleteToolCall(id) {
+		for (const tc of this.#turnToolCalls) if (tc.id === id) {
+			this.#turnToolCalls.delete(tc);
+			const count = this.#toolCallChecksums.get(tc.checksum) ?? 1;
+			if (count <= 1) this.#toolCallChecksums.delete(tc.checksum);
+			else this.#toolCallChecksums.set(tc.checksum, count - 1);
+			break;
+		}
+		await this.#deleteToolCall(this, id);
+		this.#hooks.runner("deletedToolCall").run(id);
+	}
+	/** @internal Set by {@link @nhtio/adk!DispatchRunner} after construction. */
+	_setDispatchId(id) {
+		this.#dispatchId = id;
+	}
+	/** @internal Updated by {@link @nhtio/adk!DispatchRunner} on each iteration. */
+	_setIteration(n) {
+		this.#iteration = n;
+	}
+	/** @internal Accessor used by {@link @nhtio/adk!DispatchRunner} to register forwarding handlers. */
+	_getHooks() {
+		return this.#hooks;
+	}
+	/**
+	* Returns how many times a tool call with the given checksum has been stored in this execution.
+	*
+	* @remarks
+	* Checksums are computed over `tool + args` (see {@link @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.
+	*
+	* @param checksum - The `ToolCall.checksum` value to look up.
+	*/
+	toolCallCount(checksum) {
+		return this.#toolCallChecksums.get(checksum) ?? 0;
+	}
+	/**
+	* Signals successful completion of this execution.
+	*
+	* @remarks
+	* Sets the context's internal signal flag. The {@link @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 {@link @nhtio/adk!E_LLM_EXECUTION_ALREADY_SIGNALLED} when the context has already been signalled
+	*   (whether via `ack()` or `nack()`).
+	*/
+	ack() {
+		if (this.#signalled !== void 0) throw new E_LLM_EXECUTION_ALREADY_SIGNALLED();
+		this.#signalled = "ack";
+		for (const handler of this.#ackHandlers) try {
+			handler();
+		} catch {}
+	}
+	/**
+	* Registers a handler to run when this context completes successfully via {@link ack}.
+	*
+	* @remarks
+	* The handler does NOT fire on {@link 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.
+	*
+	* @param handler - Callback invoked when `ack()` is called.
+	* @returns An unsubscribe function that removes the handler.
+	*
+	* @see {@link @nhtio/adk!ToolRegistry.bindContext}
+	* @see {@link @nhtio/adk!SpooledArtifact.forgeTools}
+	*/
+	onAck(handler) {
+		this.#ackHandlers.add(handler);
+		return () => {
+			this.#ackHandlers.delete(handler);
+		};
+	}
+	/**
+	* Signals failed completion of this execution, optionally with an error.
+	*
+	* @remarks
+	* Sets the context's internal signal flag and stores the error. The {@link @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.
+	*
+	* @param error - Optional error describing the failure. If omitted, a generic Error is used.
+	* @throws {@link @nhtio/adk!E_LLM_EXECUTION_ALREADY_SIGNALLED} when the context has already been signalled.
+	*/
+	nack(error) {
+		if (this.#signalled !== void 0) throw new E_LLM_EXECUTION_ALREADY_SIGNALLED();
+		this.#signalled = "nack";
+		this.#nackError = error ?? /* @__PURE__ */ new Error("LLM execution was nacked without an explicit error.");
+	}
+	/**
+	* Returns `true` if `value` is a {@link DispatchContext} instance.
+	*
+	* @remarks
+	* Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety. The ADK does not export the
+	* `DispatchContext` class itself as a constructable value — use this guard plus the
+	* {@link DispatchContext} type for runtime detection and TypeScript narrowing.
+	*
+	* @param value - The value to test.
+	* @returns `true` when `value` is a {@link DispatchContext} instance.
+	*/
+	static isDispatchContext(value) {
+		return isInstanceOf(value, "DispatchContext", DispatchContext);
+	}
+};
+//#endregion
+//#region src/lib/dispatch_runner.ts
+var dispatchInputSchema = validator.object({
+	source: validator.any().custom((value, helpers) => {
+		if (value === void 0) return value;
+		if (isInstanceOf(value, "TurnContext", TurnContext)) return value;
+		return helpers.error("any.invalid");
+	}).optional(),
+	raw: validator.object().unknown(true).optional(),
+	executor: validator.function().required(),
+	turnInputPipeline: validator.array().items(validator.function()).default([]),
+	turnOutputPipeline: validator.array().items(validator.function()).default([]),
+	hooks: validator.object().optional(),
+	observers: validator.object().optional()
+});
+/**
+* Orchestrates a single LLM execution dispatch — input pipeline → executor → output pipeline —
+* looped until middleware/executor signals completion via {@link @nhtio/adk!DispatchContext.ack} /
+* {@link @nhtio/adk!DispatchContext.nack} or the abort signal fires.
+*
+* @remarks
+* `DispatchRunner` has a private constructor and is invoked via the static `dispatch()`
+* method. Each dispatch creates a fresh single-use runner that is garbage-collected after the
+* call completes — matching the `@nhtio/hooks` GC rationale already baked into the context.
+*
+* The runner owns the relationship between an {@link @nhtio/adk!DispatchContext} and its parent
+* {@link @nhtio/adk!TurnContext} (when given a source). It subscribes to the context's mutation hooks,
+* queues `ContextDelta` entries, and flushes them to the parent's Sets at the end of every
+* iteration. Emits propagate from the context's hooks → the runner's hooks → (optionally) the
+* parent `TurnContext`'s emit methods → the `TurnRunner`'s buses.
+*
+* Two hook buses, mirroring `TurnRunner`'s pattern:
+*
+* - **Functional** (`hooks`): `message`, `thought`, `toolCall` — pipeline-affecting events
+* - **Observability** (`observers`): `iterationStart`, `iterationEnd`, `dispatchStart`,
+*   `dispatchEnd`, `error`, `toolExecutionStart`, `toolExecutionEnd` — instrumentation only
+*
+* The runner has no `maxIterations`, no `maxToolCallChecksumRepeats`. Implementers use the
+* primitives — `ctx.iteration`, `ctx.toolCallCount(checksum)`, `ctx.ack()`, `ctx.nack()`,
+* `ctx.abortSignal` — to build any termination bounds they need in their own middleware.
+*/
+/**
+* Module-private token gating direct construction of {@link DispatchRunner}. Callers must use
+* {@link DispatchRunner.dispatch}; the symbol is not exported, so external code cannot satisfy
+* the guard at runtime.
+*/
+var CONSTRUCT_TOKEN = Symbol("DispatchRunner.construct");
+var DispatchRunner = class DispatchRunner {
+	#functionalHooks;
+	#observabilityHooks;
+	#inputPipeline;
+	#outputPipeline;
+	#sourceCtx;
+	#deltaQueue;
+	constructor(token, sourceCtx, turnInputPipeline, turnOutputPipeline, hooks, observers) {
+		if (token !== CONSTRUCT_TOKEN) throw new E_INVALID_LLM_DISPATCH_INPUT();
+		this.#sourceCtx = sourceCtx;
+		this.#deltaQueue = [];
+		this.#functionalHooks = new Hooks();
+		this.#observabilityHooks = new Hooks();
+		const inputPipeline = new Middleware();
+		const outputPipeline = new Middleware();
+		const wrap = (fn) => (ctx, next) => {
+			if (ctx.aborted) return next();
+			return fn(ctx, next);
+		};
+		for (const fn of turnInputPipeline) inputPipeline.add(wrap(fn));
+		for (const fn of turnOutputPipeline) outputPipeline.add(wrap(fn));
+		this.#inputPipeline = inputPipeline;
+		this.#outputPipeline = outputPipeline;
+		if (hooks) for (const key of Object.keys(hooks)) {
+			const entry = hooks[key];
+			if (!entry) continue;
+			const handlers = Array.isArray(entry) ? entry : [entry];
+			for (const h of handlers) this.#functionalHooks.add(key, h);
+		}
+		if (observers) for (const key of Object.keys(observers)) {
+			const entry = observers[key];
+			if (!entry) continue;
+			const handlers = Array.isArray(entry) ? entry : [entry];
+			for (const h of handlers) this.#observabilityHooks.add(key, h);
+		}
+	}
+	/**
+	* Returns `true` if `value` is a {@link DispatchRunner} instance.
+	*
+	* @remarks
+	* Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety.
+	*
+	* @param value - The value to test.
+	* @returns `true` when `value` is a {@link DispatchRunner} instance.
+	*/
+	static isDispatchRunner(value) {
+		return isInstanceOf(value, "DispatchRunner", DispatchRunner);
+	}
+	/**
+	* Dispatches a single LLM execution.
+	*
+	* @remarks
+	* Constructs an {@link @nhtio/adk!DispatchContext} (derived from `source` or from `raw`), runs the
+	* iteration loop, and resolves when middleware/executor signals completion via `ctx.ack()` or
+	* the abort signal fires. Rejects with the nack error when middleware/executor calls
+	* `ctx.nack(err)`. Pipeline and executor errors are wrapped, surfaced on the observability
+	* `error` hook, and re-thrown.
+	*
+	* @param input - The dispatch input. Provide either `source` (derived path) or `raw` (standalone).
+	* @throws {@link @nhtio/adk!E_INVALID_LLM_DISPATCH_INPUT} when the input does not satisfy validation, or
+	*   when neither `source` nor `raw` is provided, or when both are provided.
+	*/
+	static async dispatch(input) {
+		let resolved;
+		try {
+			resolved = validateOrThrow(dispatchInputSchema, input, true);
+		} catch (err) {
+			throw new E_INVALID_LLM_DISPATCH_INPUT({ cause: isError(err) ? err : void 0 });
+		}
+		if (!resolved.source && !resolved.raw) throw new E_INVALID_LLM_DISPATCH_INPUT();
+		if (resolved.source && resolved.raw) throw new E_INVALID_LLM_DISPATCH_INPUT();
+		const runner = new DispatchRunner(CONSTRUCT_TOKEN, resolved.source, resolved.turnInputPipeline, resolved.turnOutputPipeline, resolved.hooks, resolved.observers);
+		const llmCtx = runner.#buildContext(resolved.source, resolved.raw);
+		runner.#wireContextHooks(llmCtx);
+		await runner.#runDispatch(llmCtx, resolved.executor);
+	}
+	#buildContext(source, raw) {
+		if (source) {
+			const ac = new AbortController();
+			source.abortSignal.addEventListener("abort", () => ac.abort(), { once: true });
+			return new DispatchContext({
+				turnAbortController: ac,
+				stash: source.stash.all(),
+				systemPrompt: source.systemPrompt,
+				standingInstructions: [...source.standingInstructions],
+				memories: [...source.turnMemories],
+				retrievables: [...source.turnRetrievables],
+				messages: [...source.turnMessages],
+				thoughts: [...source.turnThoughts],
+				toolCalls: [...source.turnToolCalls],
+				tools: source.tools.all(),
+				fetchMemories: () => source.fetchMemories(),
+				fetchRetrievables: () => source.fetchRetrievables(),
+				fetchMessages: () => source.fetchMessages(),
+				fetchThoughts: () => source.fetchThoughts(),
+				fetchToolCalls: () => source.fetchToolCalls(),
+				fetchTools: () => source.fetchTools(),
+				refreshStandingInstructions: () => source.refreshStandingInstructions(),
+				storeStandingInstruction: (_c, v) => source.storeStandingInstruction(v),
+				mutateStandingInstruction: (_c, v) => source.mutateStandingInstruction(v),
+				deleteStandingInstruction: (_c, v) => source.deleteStandingInstruction(v),
+				storeMemory: (_c, v) => source.storeMemory(v),
+				mutateMemory: (_c, v) => source.mutateMemory(v),
+				deleteMemory: (_c, id) => source.deleteMemory(id),
+				storeRetrievable: (_c, v) => source.storeRetrievable(v),
+				mutateRetrievable: (_c, v) => source.mutateRetrievable(v),
+				deleteRetrievable: (_c, id) => source.deleteRetrievable(id),
+				storeMessage: (_c, v) => source.storeMessage(v),
+				mutateMessage: (_c, v) => source.mutateMessage(v),
+				deleteMessage: (_c, id) => source.deleteMessage(id),
+				storeThought: (_c, v) => source.storeThought(v),
+				mutateThought: (_c, v) => source.mutateThought(v),
+				deleteThought: (_c, id) => source.deleteThought(id),
+				storeToolCall: (_c, v) => source.storeToolCall(v),
+				mutateToolCall: (_c, v) => source.mutateToolCall(v),
+				deleteToolCall: (_c, id) => source.deleteToolCall(id),
+				waitFor: source.waitFor
+			});
+		}
+		return new DispatchContext(raw);
+	}
+	#wireContextHooks(llmCtx) {
+		const ctxHooks = llmCtx._getHooks();
+		ctxHooks.add("message", (c) => {
+			this.#functionalHooks.runner("message").run(c);
+			if (this.#sourceCtx) this.#sourceCtx.emitMessage(c);
+		});
+		ctxHooks.add("thought", (c) => {
+			this.#functionalHooks.runner("thought").run(c);
+			if (this.#sourceCtx) this.#sourceCtx.emitThought(c);
+		});
+		ctxHooks.add("toolCall", (c) => {
+			this.#functionalHooks.runner("toolCall").run(c);
+			if (this.#sourceCtx) this.#sourceCtx.emitToolCall(c);
+		});
+		ctxHooks.add("toolExecutionStart", (e) => {
+			this.#observabilityHooks.runner("toolExecutionStart").run(e);
+			if (this.#sourceCtx) this.#sourceCtx.emitToolExecutionStart(e);
+		});
+		ctxHooks.add("toolExecutionEnd", (e) => {
+			this.#observabilityHooks.runner("toolExecutionEnd").run(e);
+			if (this.#sourceCtx) this.#sourceCtx.emitToolExecutionEnd(e);
+		});
+		ctxHooks.add("storedStandingInstruction", (v) => {
+			this.#deltaQueue.push({
+				op: "store",
+				type: "standingInstruction",
+				value: v
+			});
+		});
+		ctxHooks.add("mutatedStandingInstruction", (v) => {
+			this.#deltaQueue.push({
+				op: "mutate",
+				type: "standingInstruction",
+				value: v
+			});
+		});
+		ctxHooks.add("deletedStandingInstruction", (v) => {
+			this.#deltaQueue.push({
+				op: "delete",
+				type: "standingInstruction",
+				value: v
+			});
+		});
+		ctxHooks.add("storedMemory", (v) => {
+			this.#deltaQueue.push({
+				op: "store",
+				type: "memory",
+				value: v
+			});
+		});
+		ctxHooks.add("mutatedMemory", (v) => {
+			this.#deltaQueue.push({
+				op: "mutate",
+				type: "memory",
+				value: v
+			});
+		});
+		ctxHooks.add("deletedMemory", (id) => {
+			this.#deltaQueue.push({
+				op: "delete",
+				type: "memory",
+				value: id
+			});
+		});
+		ctxHooks.add("storedRetrievable", (v) => {
+			this.#deltaQueue.push({
+				op: "store",
+				type: "retrievable",
+				value: v
+			});
+		});
+		ctxHooks.add("mutatedRetrievable", (v) => {
+			this.#deltaQueue.push({
+				op: "mutate",
+				type: "retrievable",
+				value: v
+			});
+		});
+		ctxHooks.add("deletedRetrievable", (id) => {
+			this.#deltaQueue.push({
+				op: "delete",
+				type: "retrievable",
+				value: id
+			});
+		});
+		ctxHooks.add("storedMessage", (v) => {
+			this.#deltaQueue.push({
+				op: "store",
+				type: "message",
+				value: v
+			});
+		});
+		ctxHooks.add("mutatedMessage", (v) => {
+			this.#deltaQueue.push({
+				op: "mutate",
+				type: "message",
+				value: v
+			});
+		});
+		ctxHooks.add("deletedMessage", (id) => {
+			this.#deltaQueue.push({
+				op: "delete",
+				type: "message",
+				value: id
+			});
+		});
+		ctxHooks.add("storedThought", (v) => {
+			this.#deltaQueue.push({
+				op: "store",
+				type: "thought",
+				value: v
+			});
+		});
+		ctxHooks.add("mutatedThought", (v) => {
+			this.#deltaQueue.push({
+				op: "mutate",
+				type: "thought",
+				value: v
+			});
+		});
+		ctxHooks.add("deletedThought", (id) => {
+			this.#deltaQueue.push({
+				op: "delete",
+				type: "thought",
+				value: id
+			});
+		});
+		ctxHooks.add("storedToolCall", (v) => {
+			this.#deltaQueue.push({
+				op: "store",
+				type: "toolCall",
+				value: v
+			});
+		});
+		ctxHooks.add("mutatedToolCall", (v) => {
+			this.#deltaQueue.push({
+				op: "mutate",
+				type: "toolCall",
+				value: v
+			});
+		});
+		ctxHooks.add("deletedToolCall", (id) => {
+			this.#deltaQueue.push({
+				op: "delete",
+				type: "toolCall",
+				value: id
+			});
+		});
+	}
+	/**
+	* Constructs an {@link @nhtio/adk!DispatchExecutorHelpers} instance bound to a single dispatch.
+	*
+	* @remarks
+	* Per-id stream state lives on closure-captured `Map`s, so it persists across iterations of
+	* the dispatch but cannot leak between dispatches (the runner itself is single-use and
+	* garbage-collected after `dispatch()` returns).
+	*/
+	#buildHelpers(ctx) {
+		const observabilityHooks = this.#observabilityHooks;
+		const makeLogEmitter = (level) => (entry) => {
+			const event = {
+				dispatchId: ctx.dispatchId,
+				iteration: ctx.iteration,
+				emittedAt: DateTime.now(),
+				level,
+				kind: entry.kind,
+				message: entry.message,
+				...entry.payload !== void 0 ? { payload: entry.payload } : {}
+			};
+			observabilityHooks.runner("log").run(event);
+		};
+		const log = {
+			trace: makeLogEmitter("trace"),
+			debug: makeLogEmitter("debug"),
+			info: makeLogEmitter("info"),
+			warn: makeLogEmitter("warn"),
+			error: makeLogEmitter("error")
+		};
+		const messageStreams = /* @__PURE__ */ new Map();
+		const thoughtStreams = /* @__PURE__ */ new Map();
+		const toolCallStreams = /* @__PURE__ */ new Map();
+		const buildStream = (store, id, deltaText, isComplete) => {
+			let entry = store.get(id);
+			const now = DateTime.now();
+			if (!entry) {
+				entry = {
+					full: "",
+					createdAt: now,
+					isComplete: false
+				};
+				store.set(id, entry);
+			}
+			if (entry.isComplete) throw new Error(`stream "${id}" is already complete; further chunks are not accepted`);
+			entry.full = entry.full + deltaText;
+			entry.isComplete = isComplete;
+			return {
+				id,
+				createdAt: entry.createdAt,
+				updatedAt: now,
+				full: entry.full,
+				aDelta: deltaText,
+				isComplete,
+				...isComplete ? { completedAt: now } : {}
+			};
+		};
+		return {
+			reportMessage: (id, deltaText, opts) => {
+				const isComplete = opts?.isComplete ?? false;
+				ctx.emitMessage(buildStream(messageStreams, id, deltaText, isComplete));
+			},
+			reportThought: (id, deltaText, opts) => {
+				const isComplete = opts?.isComplete ?? false;
+				ctx.emitThought(buildStream(thoughtStreams, id, deltaText, isComplete));
+			},
+			reportToolCall: (id, partial) => {
+				let entry = toolCallStreams.get(id);
+				const now = DateTime.now();
+				if (!entry) {
+					entry = {
+						isError: false,
+						isComplete: false,
+						createdAt: now
+					};
+					toolCallStreams.set(id, entry);
+				}
+				if (entry.isComplete) throw new Error(`tool call "${id}" is already complete; further updates are not accepted`);
+				if (partial.tool !== void 0) entry.tool = partial.tool;
+				if (partial.args !== void 0) entry.args = partial.args;
+				if (partial.results !== void 0) entry.results = partial.results;
+				if (partial.isError !== void 0) entry.isError = partial.isError;
+				if (partial.isComplete !== void 0) entry.isComplete = partial.isComplete;
+				if (entry.tool !== void 0 && entry.args !== void 0) entry.checksum = sha256(canonicalStringify({
+					tool: entry.tool,
+					args: entry.args
+				}));
+				const content = {
+					id,
+					tool: entry.tool ?? "",
+					args: entry.args,
+					checksum: entry.checksum ?? "",
+					createdAt: entry.createdAt,
+					updatedAt: now,
+					isComplete: entry.isComplete,
+					isError: entry.isError,
+					...entry.results !== void 0 ? { results: entry.results } : {},
+					...entry.isComplete ? { completedAt: now } : {}
+				};
+				ctx.emitToolCall(content);
+			},
+			log
+		};
+	}
+	async #runDispatch(llmCtx, executor) {
+		const dispatchId = v6();
+		llmCtx._setDispatchId(dispatchId);
+		const dispatchStartedAt = DateTime.now();
+		this.#observabilityHooks.runner("dispatchStart").run({
+			dispatchId,
+			startedAt: dispatchStartedAt
+		});
+		const helpers = this.#buildHelpers(llmCtx);
+		let iteration = 0;
+		let dispatchError;
+		try {
+			while (!llmCtx.aborted && !llmCtx.isSignalled) {
+				llmCtx._setIteration(iteration);
+				const iterationStartedAt = DateTime.now();
+				this.#observabilityHooks.runner("iterationStart").run({
+					dispatchId,
+					iteration,
+					startedAt: iterationStartedAt
+				});
+				await this.#runPipeline(this.#inputPipeline.runner(), llmCtx, "input");
+				if (llmCtx.aborted || llmCtx.isSignalled) {
+					if (llmCtx.isAcked && !llmCtx.aborted) await this.#flush();
+					else this.#deltaQueue.length = 0;
+					break;
+				}
+				try {
+					await executor(llmCtx, helpers);
+				} catch (err) {
+					if (this.#isAbortError(err)) {
+						this.#deltaQueue.length = 0;
+						break;
+					}
+					const wrapped = new E_LLM_EXECUTION_EXECUTOR_ERROR({ cause: isError(err) ? err : void 0 });
+					this.#observabilityHooks.runner("error").run(wrapped);
+					this.#deltaQueue.length = 0;
+					throw wrapped;
+				}
+				if (llmCtx.aborted || llmCtx.isSignalled) {
+					if (llmCtx.isAcked && !llmCtx.aborted) await this.#flush();
+					else this.#deltaQueue.length = 0;
+					break;
+				}
+				await this.#runPipeline(this.#outputPipeline.runner(), llmCtx, "output");
+				await this.#flush();
+				const iterationEndedAt = DateTime.now();
+				this.#observabilityHooks.runner("iterationEnd").run({
+					dispatchId,
+					iteration,
+					startedAt: iterationStartedAt,
+					endedAt: iterationEndedAt,
+					durationMs: iterationEndedAt.diff(iterationStartedAt).milliseconds
+				});
+				iteration++;
+			}
+		} catch (err) {
+			dispatchError = isError(err) ? err : new Error(String(err));
+		}
+		const status = dispatchError ? "nack" : llmCtx.nackError ? "nack" : llmCtx.isAcked ? "ack" : "aborted";
+		const finalError = dispatchError ?? llmCtx.nackError;
+		if (!dispatchError && llmCtx.nackError) {
+			const nackErr = llmCtx.nackError;
+			const wrapped = isInstanceOf(nackErr, "BaseException") ? nackErr : new E_LLM_EXECUTION_EXECUTOR_ERROR({ cause: isError(nackErr) ? nackErr : void 0 });
+			this.#observabilityHooks.runner("error").run(wrapped);
+		}
+		const dispatchEndedAt = DateTime.now();
+		this.#observabilityHooks.runner("dispatchEnd").run({
+			dispatchId,
+			status,
+			error: finalError,
+			iterations: iteration,
+			startedAt: dispatchStartedAt,
+			endedAt: dispatchEndedAt,
+			durationMs: dispatchEndedAt.diff(dispatchStartedAt).milliseconds
+		});
+		if (finalError) throw finalError;
+	}
+	async #runPipeline(pipeline, llmCtx, label) {
+		let pipelineError;
+		let reached = false;
+		await pipeline.errorHandler(async (error) => {
+			if (this.#isAbortError(error)) return;
+			pipelineError = new E_DISPATCH_PIPELINE_ERROR({ cause: isError(error) ? error : void 0 });
+		}).finalHandler(async () => {
+			reached = true;
+		}).run((fn, next) => Promise.resolve(fn(llmCtx, next)));
+		if (pipelineError) {
+			this.#observabilityHooks.runner("error").run(pipelineError);
+			throw pipelineError;
+		}
+		if (!reached && !llmCtx.aborted && !llmCtx.isSignalled) {
+			const shortCircuitError = new E_PIPELINE_SHORT_CIRCUITED([`dispatch-${label}`]);
+			this.#observabilityHooks.runner("error").run(shortCircuitError);
+			throw shortCircuitError;
+		}
+	}
+	#isAbortError(err) {
+		return isError(err) && isInstanceOf(err, "AbortError");
+	}
+	async #flush() {
+		if (!this.#sourceCtx) {
+			this.#deltaQueue.length = 0;
+			return;
+		}
+		while (this.#deltaQueue.length > 0) {
+			const delta = this.#deltaQueue.shift();
+			this.#applyDeltaToParent(delta);
+		}
+	}
+	#applyDeltaToParent(delta) {
+		const ctx = this.#sourceCtx;
+		const { op, type, value } = delta;
+		if (type === "standingInstruction") {
+			const t = value;
+			if (op === "store" || op === "mutate") ctx.standingInstructions.add(t);
+			else ctx.standingInstructions.delete(t);
+			return;
+		}
+		if (type === "memory") {
+			if (op === "store" || op === "mutate") ctx.turnMemories.add(value);
+			else for (const m of ctx.turnMemories) if (m.id === value) {
+				ctx.turnMemories.delete(m);
+				break;
+			}
+			return;
+		}
+		if (type === "retrievable") {
+			if (op === "store" || op === "mutate") ctx.turnRetrievables.add(value);
+			else for (const r of ctx.turnRetrievables) if (r.id === value) {
+				ctx.turnRetrievables.delete(r);
+				break;
+			}
+			return;
+		}
+		if (type === "message") {
+			if (op === "store" || op === "mutate") ctx.turnMessages.add(value);
+			else for (const m of ctx.turnMessages) if (m.id === value) {
+				ctx.turnMessages.delete(m);
+				break;
+			}
+			return;
+		}
+		if (type === "thought") {
+			if (op === "store" || op === "mutate") ctx.turnThoughts.add(value);
+			else for (const t of ctx.turnThoughts) if (t.id === value) {
+				ctx.turnThoughts.delete(t);
+				break;
+			}
+			return;
+		}
+		if (type === "toolCall") {
+			if (op === "store" || op === "mutate") ctx.turnToolCalls.add(value);
+			else for (const tc of ctx.turnToolCalls) if (tc.id === value) {
+				ctx.turnToolCalls.delete(tc);
+				break;
+			}
+			return;
+		}
+	}
+};
+//#endregion
+export { DispatchContext as n, TurnContext as r, DispatchRunner as t };
+
+//# sourceMappingURL=dispatch_runner-9j6bXHL3.mjs.map