@nhtio/adk 0.1.0-master-f0aa531d

package/lib/exceptions/runtime.d.ts

@@ -0,0 +1,370 @@
+/**
+ * Thrown by {@link @nhtio/adk!TurnRunner} when the supplied config object fails schema validation at
+ * construction time.
+ *
+ * @remarks
+ * Marked fatal — a misconfigured runner must not be allowed to execute turns.
+ *
+ * @group Turn Runner Construction
+ */
+export declare const E_INVALID_TURN_RUNNER_CONFIG: import("../utils/exceptions").CreatedException<[
+]>;
+/**
+ * Thrown by {@link @nhtio/adk!TurnRunner} when the {@link @nhtio/adk!TurnContext} supplied to `run` fails schema
+ * validation.
+ *
+ * @remarks
+ * Marked fatal — an invalid context indicates a programming error in the caller, not a
+ * recoverable runtime condition. Thrown synchronously out of `run()` before `turnStart` is
+ * emitted.
+ *
+ * @group Turn Input Validation
+ */
+export declare const E_INVALID_TURN_CONTEXT: import("../utils/exceptions").CreatedException<[
+]>;
+/**
+ * Emitted (via the `error` event) when a non-abort error propagates out of the input
+ * middleware pipeline during {@link @nhtio/adk!TurnRunner.run}.
+ *
+ * @remarks
+ * Not fatal — the turn runner emits this on the `error` event rather than throwing, so
+ * registered listeners can handle or log the failure without crashing the pipeline. Dispatch
+ * and output middleware are skipped; `turnEnd` still fires.
+ *
+ * @group Pipelines
+ */
+export declare const E_INPUT_PIPELINE_ERROR: import("../utils/exceptions").CreatedException<[
+]>;
+/**
+ * Emitted (via the `error` event) when a non-abort error propagates out of the output
+ * middleware pipeline during {@link @nhtio/adk!TurnRunner.run}.
+ *
+ * @remarks
+ * Not fatal — the turn runner emits this on the `error` event rather than throwing, so
+ * registered listeners can handle or log the failure without crashing the pipeline. `turnEnd`
+ * still fires.
+ *
+ * @group Pipelines
+ */
+export declare const E_OUTPUT_PIPELINE_ERROR: import("../utils/exceptions").CreatedException<[
+]>;
+/**
+ * Emitted (via the `error` event) when a middleware pipeline resolves without reaching its
+ * terminal handler and without the turn being aborted. Indicates that some middleware
+ * returned without calling `next` and without signalling a deliberate refusal via the turn's
+ * abort controller.
+ *
+ * @remarks
+ * Not fatal — the runner emits this on the `error` event so the failure is observable, then
+ * proceeds to short-circuit the remainder of the turn the same way any other pipeline error
+ * would. The constructor takes a single positional argument identifying the pipeline that
+ * short-circuited: one of `'turn-input'`, `'turn-output'`, `'dispatch-input'`, or `'dispatch-output'`.
+ *
+ * Deliberate refusals should call `ctx.abort(reason)`, which sets the `'aborted'` outcome
+ * instead of emitting this error.
+ *
+ * @warning
+ * This is a **detection condition**, not a thrown exception. The runner constructs and emits
+ * the code itself when it detects a missing `next()` on the unwind — nothing in user code
+ * throws it. Upstream post-steps still run normally.
+ *
+ * @example
+ * ```ts
+ * throw new E_PIPELINE_SHORT_CIRCUITED(['turn-input'])
+ * ```
+ *
+ * @group Pipelines
+ */
+export declare const E_PIPELINE_SHORT_CIRCUITED: import("../utils/exceptions").CreatedException<[
+    string
+]>;
+/**
+ * Thrown when a registry is initialised with a value that is defined but not a plain object.
+ *
+ * @remarks
+ * Registries expect either `undefined` (empty start) or a plain object as their initial value.
+ * Passing a primitive, array, class instance, or other non-object signals a programming error
+ * in the caller.
+ *
+ * @group Primitive Validation
+ */
+export declare const E_INVALID_INITIAL_REGISTRY_VALUE: import("../utils/exceptions").CreatedException<[
+]>;
+/**
+ * Thrown when a {@link @nhtio/adk!Memory} is initialised with a value that fails schema validation.
+ *
+ * @remarks
+ * `Memory` requires all fields — `id`, `content`, `confidence`, `importance`, `createdAt`,
+ * `updatedAt` — to be present and of the correct type. Passing an incomplete or incorrectly
+ * typed object signals a programming error in the caller, not a recoverable runtime condition.
+ *
+ * @group Primitive Validation
+ */
+export declare const E_INVALID_INITIAL_MEMORY_VALUE: import("../utils/exceptions").CreatedException<[
+]>;
+/**
+ * Thrown when a {@link @nhtio/adk!Retrievable} is initialised with a value that fails schema validation.
+ *
+ * @remarks
+ * `Retrievable` requires `id`, `content`, `trustTier`, `createdAt`, and `updatedAt` to be present
+ * and of the correct type, and `trustTier` must be one of `'first-party'`, `'third-party-public'`,
+ * or `'third-party-private'`. The `trustTier` decision must be made consciously by the retrieval
+ * middleware at construction time — there is no default. Passing an incomplete or incorrectly
+ * typed object signals a programming error in the caller, not a recoverable runtime condition.
+ *
+ * @group Primitive Validation
+ */
+export declare const E_INVALID_INITIAL_RETRIEVABLE_VALUE: import("../utils/exceptions").CreatedException<[
+]>;
+/**
+ * Thrown when a {@link @nhtio/adk!Message} is initialised with a value that fails schema validation.
+ *
+ * @remarks
+ * `Message` requires `id`, `role` (`user` or `assistant`), `content`, `createdAt`, and
+ * `updatedAt` to be present and of the correct type. Passing an incomplete or incorrectly
+ * typed object signals a programming error in the caller, not a recoverable runtime condition.
+ *
+ * @group Primitive Validation
+ */
+export declare const E_INVALID_INITIAL_MESSAGE_VALUE: import("../utils/exceptions").CreatedException<[
+]>;
+/**
+ * Thrown when an {@link @nhtio/adk!Identity} is initialised with a value that fails schema validation.
+ *
+ * @remarks
+ * `Identity` requires both `identifier` (string or number) and `representation` (string or
+ * {@link @nhtio/adk!Tokenizable}) to be present and of the correct type. Passing an incomplete or
+ * incorrectly typed object signals a programming error in the caller.
+ *
+ * @group Primitive Validation
+ */
+export declare const E_INVALID_INITIAL_IDENTITY_VALUE: import("../utils/exceptions").CreatedException<[
+]>;
+/**
+ * Thrown when a {@link @nhtio/adk!Thought} is initialised with a value that fails schema validation.
+ *
+ * @remarks
+ * `Thought` requires `id`, `content`, `createdAt`, and `updatedAt` to be present and of the
+ * correct type. Passing an incomplete or incorrectly typed object signals a programming error
+ * in the caller, not a recoverable runtime condition.
+ *
+ * @group Primitive Validation
+ */
+export declare const E_INVALID_INITIAL_THOUGHT_VALUE: import("../utils/exceptions").CreatedException<[
+]>;
+/**
+ * Thrown when a {@link @nhtio/adk!TurnGate} is constructed with a value that fails schema validation.
+ *
+ * @remarks
+ * Fatal — bad construction arguments indicate a programming error in the caller.
+ *
+ * @group Gates
+ */
+export declare const E_INVALID_INITIAL_TURN_GATE_VALUE: import("../utils/exceptions").CreatedException<[
+]>;
+/**
+ * Thrown synchronously in the caller's context when {@link @nhtio/adk!TurnGate.resolve} is called with a
+ * value that fails the gate's schema.
+ *
+ * @remarks
+ * Fatal — passing the wrong type to `resolve()` is a programming error. The internal promise is
+ * NOT settled when this is thrown; the gate remains open.
+ *
+ * @group Gates
+ */
+export declare const E_INVALID_TURN_GATE_RESOLUTION: import("../utils/exceptions").CreatedException<[
+]>;
+/**
+ * Thrown (as a rejection reason) when a {@link @nhtio/adk!TurnGate} times out before being resolved.
+ *
+ * @remarks
+ * Not fatal — a timeout is a recoverable runtime condition; the caller may retry or surface it
+ * to the user.
+ *
+ * @warning
+ * A timeout does **not** cancel the external event or clear any remote queue. The gate closes
+ * locally, but whatever external system was expected to call `gate.resolve()` may still fire
+ * later. Orphaned external state must be handled by the caller.
+ *
+ * @group Gates
+ */
+export declare const E_TURN_GATE_TIMEOUT: import("../utils/exceptions").CreatedException<[
+]>;
+/**
+ * Thrown (as a rejection reason) when a {@link @nhtio/adk!TurnGate} is aborted — either because the turn's
+ * `AbortSignal` fired or because {@link @nhtio/adk!TurnGate.abort} was called directly.
+ *
+ * @remarks
+ * Not fatal — abort is an intentional cancellation, not an error in the caller.
+ *
+ * @group Gates
+ */
+export declare const E_TURN_GATE_ABORTED: import("../utils/exceptions").CreatedException<[
+]>;
+/**
+ * Thrown when a {@link @nhtio/adk!SpooledArtifact} is constructed with a value that does not implement the
+ * {@link @nhtio/adk!SpoolReader} interface.
+ *
+ * @remarks
+ * Validated at construction time via {@link @nhtio/adk!implementsSpoolReader}. Passing anything that lacks
+ * `line`, `byteLength`, or `lineCount` as callable functions signals a programming error in the
+ * caller.
+ *
+ * @group Artifacts
+ */
+export declare const E_NOT_A_SPOOL_READER: import("../utils/exceptions").CreatedException<[
+]>;
+/**
+ * Thrown when a Media is constructed with a value that does not implement the MediaReader
+ * interface.
+ *
+ * @remarks
+ * Validated at construction time. Passing anything that lacks `stream` or `byteLength` as
+ * callable functions signals a programming error in the caller.
+ *
+ * @group Artifacts
+ */
+export declare const E_NOT_A_MEDIA_READER: import("../utils/exceptions").CreatedException<[
+]>;
+/**
+ * Thrown when a Media is initialised with a value that fails schema validation.
+ *
+ * @remarks
+ * Fatal — bad construction arguments indicate a programming error in the caller.
+ *
+ * @group Artifacts
+ */
+export declare const E_INVALID_INITIAL_MEDIA_VALUE: import("../utils/exceptions").CreatedException<[
+]>;
+/**
+ * Thrown when a {@link @nhtio/adk!ToolCall} is initialised with a value that fails schema validation.
+ *
+ * @remarks
+ * `ToolCall` requires `id`, `tool`, `args`, `checksum`, `isComplete`, `isError`, `createdAt`,
+ * and `updatedAt` to be present and of the correct type. Passing an incomplete or incorrectly
+ * typed object signals a programming error in the caller, not a recoverable runtime condition.
+ *
+ * @group Primitive Validation
+ */
+export declare const E_INVALID_INITIAL_TOOL_CALL_VALUE: import("../utils/exceptions").CreatedException<[
+]>;
+/**
+ * Thrown when a {@link @nhtio/adk!Tool} is constructed with a value that fails schema validation.
+ *
+ * @remarks
+ * Fatal — bad construction arguments indicate a programming error in the caller.
+ *
+ * @group Tools
+ */
+export declare const E_INVALID_INITIAL_TOOL_VALUE: import("../utils/exceptions").CreatedException<[
+]>;
+/**
+ * Thrown synchronously when {@link @nhtio/adk!Tool.validate} is called with arguments that fail the tool's
+ * input schema.
+ *
+ * @remarks
+ * Not fatal — an arg validation failure in the tool call loop is a caller mistake that can be
+ * surfaced as an error response. The tool handler is NOT called when this is thrown.
+ *
+ * @group Tools
+ */
+export declare const E_INVALID_TOOL_ARGS: import("../utils/exceptions").CreatedException<[
+]>;
+/**
+ * Thrown (as a rejection reason) when a {@link @nhtio/adk!Tool}'s handler throws during execution.
+ *
+ * @remarks
+ * Not fatal — a downstream tool failure is a recoverable runtime condition. The tool call loop
+ * catches this error specifically to report the failure back to the model rather than crashing
+ * the pipeline.
+ *
+ * @group Tools
+ */
+export declare const E_TOOL_DOWNSTREAM_ERROR: import("../utils/exceptions").CreatedException<[
+]>;
+/**
+ * Thrown when {@link @nhtio/adk!ToolRegistry.register} is called for a tool name that is already registered
+ * and `overwrite` is not `true`.
+ *
+ * @remarks
+ * Fatal — accidentally overwriting a registered tool indicates a programming error. Pass
+ * `overwrite: true` to replace an existing tool intentionally.
+ *
+ * @group Tools
+ */
+export declare const E_TOOL_ALREADY_REGISTERED: import("../utils/exceptions").CreatedException<[
+]>;
+/**
+ * Thrown when {@link @nhtio/adk!DispatchContext} is constructed with a value that fails schema validation.
+ *
+ * @remarks
+ * Fatal — bad construction arguments indicate a programming error in the caller.
+ *
+ * @group Dispatch
+ */
+export declare const E_INVALID_LLM_EXECUTION_CONTEXT: import("../utils/exceptions").CreatedException<[
+]>;
+/**
+ * Thrown (as a rejection reason) when {@link @nhtio/adk!DispatchContext.waitFor} is called on a
+ * standalone context that was constructed without a `waitFor` function.
+ *
+ * @remarks
+ * Not fatal — the caller can catch this and handle the case where gate suspension is not
+ * supported for this execution context.
+ *
+ * @group Dispatch
+ */
+export declare const E_LLM_EXECUTION_GATE_NOT_SUPPORTED: import("../utils/exceptions").CreatedException<[
+]>;
+/**
+ * Thrown when {@link @nhtio/adk!DispatchContext.ack} or {@link @nhtio/adk!DispatchContext.nack} is called on a
+ * context that has already been signalled.
+ *
+ * @remarks
+ * Fatal — signalling twice is a programming error in the caller. The first signal wins; the
+ * second call is rejected loudly so callers cannot accidentally race between ack and nack.
+ *
+ * @danger
+ * Signalling is **not** silently idempotent. The first `ack()` or `nack()` wins; the second
+ * throws immediately. Guard with `if (!ctx.isSignalled)` when more than one seam may signal.
+ *
+ * @group Dispatch
+ */
+export declare const E_LLM_EXECUTION_ALREADY_SIGNALLED: import("../utils/exceptions").CreatedException<[
+]>;
+/**
+ * Thrown when {@link @nhtio/adk!DispatchRunner.dispatch} receives an input that fails schema validation.
+ *
+ * @remarks
+ * Fatal — invalid dispatch input indicates a programming error in the caller.
+ *
+ * @group Dispatch
+ */
+export declare const E_INVALID_LLM_DISPATCH_INPUT: import("../utils/exceptions").CreatedException<[
+]>;
+/**
+ * Emitted (via the observability `error` hook) and re-thrown when a non-abort error propagates
+ * out of the input or output middleware pipeline during {@link @nhtio/adk!DispatchRunner.dispatch}.
+ *
+ * @remarks
+ * Not fatal — pipeline errors are recoverable runtime conditions. `dispatch()` rejects with this
+ * exception so callers can handle the failure via try/catch. Both `dispatchInputPipeline` and
+ * `dispatchOutputPipeline` share this one code — the runner does not split input vs. output at
+ * this layer.
+ *
+ * @group Pipelines
+ */
+export declare const E_DISPATCH_PIPELINE_ERROR: import("../utils/exceptions").CreatedException<[
+]>;
+/**
+ * Emitted (via the observability `error` hook) and re-thrown when the user-supplied executor
+ * callback throws during {@link @nhtio/adk!DispatchRunner.dispatch}.
+ *
+ * @remarks
+ * Not fatal — executor errors are recoverable runtime conditions. `dispatch()` rejects with this
+ * exception so callers can handle the failure via try/catch.
+ *
+ * @group Dispatch
+ */
+export declare const E_LLM_EXECUTION_EXECUTOR_ERROR: import("../utils/exceptions").CreatedException<[
+]>;

package/lib/helpers/media_readers.d.ts

@@ -0,0 +1,39 @@
+import type { MediaReader } from "../contracts/media_reader";
+/**
+ * Constructs a {@link @nhtio/adk!MediaReader} backed by an in-memory `Uint8Array`.
+ *
+ * @remarks
+ * Each `stream()` call returns a fresh single-chunk `ReadableStream` over the same buffer. The
+ * reader is re-openable by construction — call `stream()` as many times as needed.
+ *
+ * @param bytes - The buffer to serve.
+ * @returns A {@link @nhtio/adk!MediaReader} that re-reads `bytes` on every call.
+ */
+export declare const inMemoryMediaReader: (bytes: Uint8Array) => MediaReader;
+/**
+ * Constructs a {@link @nhtio/adk!MediaReader} backed by a fetch call.
+ *
+ * @remarks
+ * Each `stream()` call re-issues the fetch. Tool authors whose underlying source is rate-limited
+ * or expensive must cache locally before constructing the reader — the framework cannot make
+ * that decision for them.
+ *
+ * `byteLength()` returns `undefined` because most remote sources do not promise it without an
+ * extra HEAD request; consumers that need a byte size should resolve it out-of-band.
+ *
+ * @param url - The URL to fetch on each call.
+ * @param init - Optional `fetch` init forwarded verbatim.
+ * @returns A {@link @nhtio/adk!MediaReader} that re-issues `fetch(url, init)` on every call.
+ */
+export declare const fromFetch: (url: string | URL, init?: RequestInit) => MediaReader;
+/**
+ * Constructs a {@link @nhtio/adk!MediaReader} backed by a browser `File` or `Blob`.
+ *
+ * @remarks
+ * Each `stream()` call re-streams the underlying File via `File.stream()`. `byteLength()`
+ * resolves from `file.size`.
+ *
+ * @param file - The browser `File` or `Blob` to stream.
+ * @returns A {@link @nhtio/adk!MediaReader} that re-streams `file` on every call.
+ */
+export declare const fromWebFile: (file: Blob) => MediaReader;

package/lib/turn_runner.d.ts

@@ -0,0 +1,144 @@
+import { RawTurnContext } from "./contracts/turn_runner_context";
+import type { TurnRunnerConfig } from "./contracts/turn_runner_config";
+import type { TurnEvent, TurnEventListener, TurnObservabilityEvent, TurnObservabilityEventListener } from "./types/turn_runner";
+export type { TurnPipelineMiddlewareFn, TurnStreamableContent, TurnToolCallContent, TurnStartEvent, TurnEndEvent, TurnGateClosedEvent, ToolExecutionStartEvent, ToolExecutionEndEvent, EmitMessageFn, EmitThoughtFn, EmitToolCallFn, EmitToolExecutionStartFn, EmitToolExecutionEndFn, OpenGateFn, TurnEvents, TurnEvent, TurnEventListener, TurnObservabilityEvents, TurnObservabilityEvent, TurnObservabilityEventListener, } from "./types/turn_runner";
+/**
+ * Executes a single agent turn through paired input and output middleware pipelines.
+ *
+ * @remarks
+ * Construction validates `config` eagerly and throws {@link @nhtio/adk!E_INVALID_TURN_RUNNER_CONFIG} if it
+ * does not satisfy the schema — fail-fast so misconfiguration surfaces before any turn runs.
+ *
+ * Each call to {@link TurnRunner.run} threads a {@link @nhtio/adk!TurnContext} through the input pipeline,
+ * invokes the model, then threads the result through the output pipeline. Middleware on each side
+ * can read and mutate the context for pre- and post-processing (e.g. message normalisation, tool
+ * call dispatch, response filtering).
+ *
+ * **Two event buses:**
+ * - Functional bus (`on` / `off` / `once`): `message`, `thought`, `toolCall` — pipeline-affecting
+ *   events that middleware raises throughout turn execution.
+ * - Observability bus (`observe` / `unobserve` / `observeOnce`): `turnStart`, `turnEnd`,
+ *   `turnGateOpen`, `turnGateClosed`, `error` — instrumentation-only events that monitor execution
+ *   without participating in it.
+ *
+ * Streaming content is surfaced via `message` and `thought` events; tool call lifecycle via
+ * `toolCall`; non-fatal pipeline errors via the observability `error` event; gate lifecycle via
+ * `turnGateOpen` and `turnGateClosed` — all throughout execution.
+ *
+ * @example
+ * ```ts
+ * const runner = new TurnRunner({
+ *   fetchMemoriesCallback: async (ctx) => memoryStore.query(ctx),
+ *   fetchMessagesCallback: async (ctx) => messageStore.history(ctx),
+ *   fetchThoughtsCallback: async (ctx) => thoughtStore.history(ctx),
+ *   fetchToolCallsCallback: async (ctx) => toolCallStore.history(ctx),
+ * })
+ * // Functional bus — pipeline events
+ * runner.on('message', (chunk) => process.stdout.write(chunk.aDelta))
+ * // Observability bus — instrumentation
+ * runner.observe('error', (err) => console.error(err.toString()))
+ * runner.observe('turnStart', ({ turnId }) => console.log('turn started', turnId))
+ * runner.observe('turnGateOpen', (gate) => {
+ *   if (gate.reason === 'tool_approval') {
+ *     gate.resolve(true) // approve immediately for this example
+ *   }
+ * })
+ * await runner.run({
+ *   turnAbortController: new AbortController(),
+ *   systemPrompt: 'You are a helpful assistant.',
+ *   standingInstructions: [],
+ * })
+ * ```
+ */
+export declare class TurnRunner {
+    #private;
+    /**
+     * Returns `true` if `value` is a {@link TurnRunner} instance.
+     *
+     * @remarks
+     * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety.
+     *
+     * @param value - The value to test.
+     * @returns `true` when `value` is a {@link TurnRunner} instance.
+     */
+    static isTurnRunner(value: unknown): value is TurnRunner;
+    /**
+     * @param config - Construction-time configuration validated against {@link turnRunnerConfigSchema}.
+     * @throws {@link @nhtio/adk!E_INVALID_TURN_RUNNER_CONFIG} when `config` does not satisfy the schema.
+     */
+    constructor(config: TurnRunnerConfig);
+    /**
+     * Removes a previously registered functional listener for `event`.
+     *
+     * @param event - The event to stop listening to.
+     * @param listener - The listener function to remove.
+     * @returns `this` for chaining.
+     */
+    off<K>(event: TurnEvent<K>, listener: TurnEventListener<K>): this;
+    /**
+     * Registers a persistent functional listener for `event`.
+     *
+     * @param event - The event to listen to.
+     * @param listener - The function to call on each emission.
+     * @returns `this` for chaining.
+     */
+    on<K>(event: TurnEvent<K>, listener: TurnEventListener<K>): this;
+    /**
+     * Registers a one-time functional listener for `event` that is automatically removed after the
+     * first emission.
+     *
+     * @param event - The event to listen to.
+     * @param listener - The function to call on the next emission.
+     * @returns `this` for chaining.
+     */
+    once<K>(event: TurnEvent<K>, listener: TurnEventListener<K>): this;
+    /**
+     * Removes a previously registered observability listener for `event`.
+     *
+     * @param event - The event to stop observing.
+     * @param listener - The listener function to remove.
+     * @returns `this` for chaining.
+     */
+    unobserve<K>(event: TurnObservabilityEvent<K>, listener: TurnObservabilityEventListener<K>): this;
+    /**
+     * Registers a persistent observability listener for `event`.
+     *
+     * @remarks
+     * Use the observability bus (`observe` / `unobserve` / `observeOnce`) for instrumentation:
+     * turn lifecycle, gate lifecycle, and non-fatal errors. Use the functional bus (`on` / `off` /
+     * `once`) for pipeline-affecting events: `message`, `thought`, `toolCall`.
+     *
+     * @param event - The event to observe.
+     * @param listener - The function to call on each emission.
+     * @returns `this` for chaining.
+     */
+    observe<K>(event: TurnObservabilityEvent<K>, listener: TurnObservabilityEventListener<K>): this;
+    /**
+     * Registers a one-time observability listener for `event` that is automatically removed after
+     * the first emission.
+     *
+     * @param event - The event to observe once.
+     * @param listener - The function to call on the next emission.
+     * @returns `this` for chaining.
+     */
+    observeOnce<K>(event: TurnObservabilityEvent<K>, listener: TurnObservabilityEventListener<K>): this;
+    /**
+     * Executes a single agent turn against the provided raw context.
+     *
+     * @remarks
+     * Returns `Promise<void>` intentionally — all meaningful output surfaces via events, not return
+     * values. Register listeners before calling `run`: observability events (`turnStart`, `turnEnd`)
+     * bracket execution; functional events (`message`, `thought`, `toolCall`) fire throughout;
+     * observability `error` carries non-fatal pipeline failures; `turnGateOpen` and `turnGateClosed`
+     * fire when middleware suspends via `ctx.waitFor()`. Awaiting this method only tells you the
+     * pipeline has finished, not what it produced.
+     *
+     * Constructs a validated {@link @nhtio/adk!TurnContext} from `context` (throwing
+     * {@link @nhtio/adk!E_INVALID_TURN_CONTEXT} on failure), then runs the input middleware pipeline.
+     * Abort signals are silently swallowed.
+     *
+     * @param context - Raw input validated and wrapped into a {@link @nhtio/adk!TurnContext} before execution.
+     * @throws {@link @nhtio/adk!E_INVALID_TURN_CONTEXT} when `context` does not satisfy the schema.
+     */
+    run(context: RawTurnContext): Promise<void>;
+}