@nhtio/adk 0.1.0-master-f0aa531d

package/lib/contracts/dispatch_context.d.ts

@@ -0,0 +1,345 @@
+import { Registry } from "../classes/registry";
+import { Tokenizable } from "../classes/tokenizable";
+import { ToolRegistry } from "../classes/tool_registry";
+import type { Tool } from "../classes/tool";
+import type { Memory } from "../classes/memory";
+import type { Message } from "../classes/message";
+import type { Thought } from "../classes/thought";
+import type { ToolCall } from "../classes/tool_call";
+import type { Retrievable } from "../classes/retrievable";
+import type { DispatchContextHookRegistrations } from "../types/dispatch_context";
+import type { EmitMessageFn, EmitThoughtFn, EmitToolCallFn, EmitToolExecutionStartFn, EmitToolExecutionEndFn, OpenGateFn } from "../types/turn_runner";
+/** Retrieves memories for an LLM execution context. */
+export type DispatchMemoryRetrievalFn = (ctx: DispatchContext) => Memory[] | Promise<Memory[]>;
+/** Retrieves messages for an LLM execution context. */
+export type DispatchMessageRetrievalFn = (ctx: DispatchContext) => Message[] | Promise<Message[]>;
+/** Retrieves thoughts for an LLM execution context. */
+export type DispatchThoughtRetrievalFn = (ctx: DispatchContext) => Thought[] | Promise<Thought[]>;
+/** Retrieves tool calls for an LLM execution context. */
+export type DispatchToolCallRetrievalFn = (ctx: DispatchContext) => ToolCall[] | Promise<ToolCall[]>;
+/** Retrieves tools for an LLM execution context. */
+export type DispatchToolsRetrievalFn = (ctx: DispatchContext) => Tool[] | Promise<Tool[]>;
+/** Refreshes and returns standing instructions for an LLM execution context. */
+export type DispatchStandingInstructionsRefreshFn = (ctx: DispatchContext) => (string | Tokenizable)[] | Promise<(string | Tokenizable)[]>;
+/** Stores a new standing instruction (LLM execution context variant). */
+export type DispatchStandingInstructionStoreFn = (ctx: DispatchContext, v: string | Tokenizable) => void | Promise<void>;
+/** Updates an existing standing instruction (LLM execution context variant). */
+export type DispatchStandingInstructionMutateFn = (ctx: DispatchContext, v: string | Tokenizable) => void | Promise<void>;
+/** Removes a standing instruction (LLM execution context variant). */
+export type DispatchStandingInstructionDeleteFn = (ctx: DispatchContext, v: string | Tokenizable) => void | Promise<void>;
+/** Stores a new memory (LLM execution context variant). */
+export type DispatchMemoryStoreFn = (ctx: DispatchContext, v: Memory) => void | Promise<void>;
+/** Updates an existing memory (LLM execution context variant). */
+export type DispatchMemoryMutateFn = (ctx: DispatchContext, v: Memory) => void | Promise<void>;
+/** Removes a memory by ID (LLM execution context variant). */
+export type DispatchMemoryDeleteFn = (ctx: DispatchContext, id: string) => void | Promise<void>;
+/** Retrieves retrievable records for an LLM execution context. */
+export type DispatchRetrievableRetrievalFn = (ctx: DispatchContext) => Retrievable[] | Promise<Retrievable[]>;
+/** Stores a new retrievable record (LLM execution context variant). */
+export type DispatchRetrievableStoreFn = (ctx: DispatchContext, v: Retrievable) => void | Promise<void>;
+/** Updates an existing retrievable record (LLM execution context variant). */
+export type DispatchRetrievableMutateFn = (ctx: DispatchContext, v: Retrievable) => void | Promise<void>;
+/** Removes a retrievable record by ID (LLM execution context variant). */
+export type DispatchRetrievableDeleteFn = (ctx: DispatchContext, id: string) => void | Promise<void>;
+/** Stores a new message (LLM execution context variant). */
+export type DispatchMessageStoreFn = (ctx: DispatchContext, v: Message) => void | Promise<void>;
+/** Updates an existing message (LLM execution context variant). */
+export type DispatchMessageMutateFn = (ctx: DispatchContext, v: Message) => void | Promise<void>;
+/** Removes a message by ID (LLM execution context variant). */
+export type DispatchMessageDeleteFn = (ctx: DispatchContext, id: string) => void | Promise<void>;
+/** Stores a new thought (LLM execution context variant). */
+export type DispatchThoughtStoreFn = (ctx: DispatchContext, v: Thought) => void | Promise<void>;
+/** Updates an existing thought (LLM execution context variant). */
+export type DispatchThoughtMutateFn = (ctx: DispatchContext, v: Thought) => void | Promise<void>;
+/** Removes a thought by ID (LLM execution context variant). */
+export type DispatchThoughtDeleteFn = (ctx: DispatchContext, id: string) => void | Promise<void>;
+/** Stores a new tool call (LLM execution context variant). */
+export type DispatchToolCallStoreFn = (ctx: DispatchContext, v: ToolCall) => void | Promise<void>;
+/** Updates an existing tool call (LLM execution context variant). */
+export type DispatchToolCallMutateFn = (ctx: DispatchContext, v: ToolCall) => void | Promise<void>;
+/** Removes a tool call by ID (LLM execution context variant). */
+export type DispatchToolCallDeleteFn = (ctx: DispatchContext, id: string) => void | Promise<void>;
+/**
+ * Plain input object supplied to {@link DispatchContext} at construction time.
+ *
+ * @remarks
+ * All fetch and mutation callbacks are required — every execution context must have a persistence
+ * layer wired up, even in standalone mode. Optional pre-fetched arrays populate the context's Sets
+ * at construction time without replacing the callbacks (the callbacks are still invoked on
+ * subsequent fetch calls).
+ */
+export interface RawDispatchContext {
+    /** `AbortController` whose signal can cancel execution mid-flight. */
+    turnAbortController?: AbortController;
+    /** Arbitrary key-value store for cross-step state. */
+    stash?: Record<string, unknown>;
+    /** The system prompt for this execution. */
+    systemPrompt: string | Tokenizable;
+    /** Standing instructions for this execution. */
+    standingInstructions?: (string | Tokenizable)[];
+    /** Pre-fetched memories to populate the context at construction. */
+    memories?: Memory[];
+    /** Pre-fetched retrievable records to populate the context at construction. */
+    retrievables?: Retrievable[];
+    /** Pre-fetched messages to populate the context at construction. */
+    messages?: Message[];
+    /** Pre-fetched thoughts to populate the context at construction. */
+    thoughts?: Thought[];
+    /** Pre-fetched tool calls to populate the context at construction. */
+    toolCalls?: ToolCall[];
+    /** Pre-fetched tools to populate the tool registry at construction. */
+    tools?: Tool[];
+    /** Retrieves memories for this execution. */
+    fetchMemories: DispatchMemoryRetrievalFn;
+    /** Retrieves retrievable records for this execution. */
+    fetchRetrievables: DispatchRetrievableRetrievalFn;
+    /** Retrieves messages for this execution. */
+    fetchMessages: DispatchMessageRetrievalFn;
+    /** Retrieves thoughts for this execution. */
+    fetchThoughts: DispatchThoughtRetrievalFn;
+    /** Retrieves tool calls for this execution. */
+    fetchToolCalls: DispatchToolCallRetrievalFn;
+    /** Retrieves tools for this execution. */
+    fetchTools: DispatchToolsRetrievalFn;
+    /** Refreshes and returns standing instructions for this execution. */
+    refreshStandingInstructions: DispatchStandingInstructionsRefreshFn;
+    /** Stores a new standing instruction. */
+    storeStandingInstruction: DispatchStandingInstructionStoreFn;
+    /** Updates an existing standing instruction. */
+    mutateStandingInstruction: DispatchStandingInstructionMutateFn;
+    /** Removes a standing instruction. */
+    deleteStandingInstruction: DispatchStandingInstructionDeleteFn;
+    /** Stores a new memory. */
+    storeMemory: DispatchMemoryStoreFn;
+    /** Updates an existing memory. */
+    mutateMemory: DispatchMemoryMutateFn;
+    /** Removes a memory by ID. */
+    deleteMemory: DispatchMemoryDeleteFn;
+    /** Stores a new retrievable record. */
+    storeRetrievable: DispatchRetrievableStoreFn;
+    /** Updates an existing retrievable record. */
+    mutateRetrievable: DispatchRetrievableMutateFn;
+    /** Removes a retrievable record by ID. */
+    deleteRetrievable: DispatchRetrievableDeleteFn;
+    /** Stores a new message. */
+    storeMessage: DispatchMessageStoreFn;
+    /** Updates an existing message. */
+    mutateMessage: DispatchMessageMutateFn;
+    /** Removes a message by ID. */
+    deleteMessage: DispatchMessageDeleteFn;
+    /** Stores a new thought. */
+    storeThought: DispatchThoughtStoreFn;
+    /** Updates an existing thought. */
+    mutateThought: DispatchThoughtMutateFn;
+    /** Removes a thought by ID. */
+    deleteThought: DispatchThoughtDeleteFn;
+    /** Stores a new tool call. */
+    storeToolCall: DispatchToolCallStoreFn;
+    /** Updates an existing tool call. */
+    mutateToolCall: DispatchToolCallMutateFn;
+    /** Removes a tool call by ID. */
+    deleteToolCall: DispatchToolCallDeleteFn;
+    /** Optional hook registrations for emit events. */
+    hooks?: DispatchContextHookRegistrations;
+    /** Optional gate suspension function. When absent, `waitFor` rejects with {@link @nhtio/adk!E_LLM_EXECUTION_GATE_NOT_SUPPORTED}. */
+    waitFor?: OpenGateFn;
+}
+/**
+ * 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.
+ */
+export declare class DispatchContext {
+    #private;
+    /**
+     * @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: RawDispatchContext);
+    /**
+     * 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: string): number;
+    /**
+     * 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(): void;
+    /**
+     * 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: () => void): () => void;
+    /**
+     * 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?: Error): void;
+    /**
+     * 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: unknown): value is DispatchContext;
+    /** Unique identifier for this execution context, generated as UUIDv6 at construction time. */
+    readonly id: string;
+    /** Stable identifier for the dispatch this context belongs to; set by `DispatchRunner`. */
+    readonly dispatchId: string;
+    /** 0-based iteration count within the current dispatch; updated by `DispatchRunner`. */
+    readonly iteration: number;
+    /** `true` when the abort controller signal has fired. */
+    readonly aborted: boolean;
+    /** The `AbortSignal` from the execution's `AbortController`. */
+    readonly abortSignal: AbortSignal;
+    /**
+     * 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.
+     */
+    readonly abort: (reason?: unknown) => void;
+    /** `true` once {@link DispatchContext.ack} or {@link DispatchContext.nack} has been called. */
+    readonly isSignalled: boolean;
+    /** `true` when the context was signalled via {@link DispatchContext.ack}. */
+    readonly isAcked: boolean;
+    /** The error stored by {@link DispatchContext.nack}, or `undefined` if not nacked. */
+    readonly nackError: Error | undefined;
+    /** Arbitrary key-value store for cross-step state. */
+    readonly stash: Registry;
+    /** The system prompt for this execution. */
+    readonly systemPrompt: Tokenizable;
+    /** Standing instructions for this execution, in insertion order. */
+    readonly standingInstructions: Set<Tokenizable>;
+    /** Memories loaded for this execution. */
+    readonly turnMemories: Set<Memory>;
+    /** Retrievable records loaded for this execution. */
+    readonly turnRetrievables: Set<Retrievable>;
+    /** Messages loaded for this execution. */
+    readonly turnMessages: Set<Message>;
+    /** Thoughts loaded for this execution. */
+    readonly turnThoughts: Set<Thought>;
+    /** Tool calls loaded for this execution. */
+    readonly turnToolCalls: Set<ToolCall>;
+    /** Tool registry for this execution. */
+    readonly tools: ToolRegistry;
+    /** Fetches memories; delegates to the callback supplied at construction. */
+    readonly fetchMemories: () => Memory[] | Promise<Memory[]>;
+    /** Fetches retrievable records; delegates to the callback supplied at construction. */
+    readonly fetchRetrievables: () => Retrievable[] | Promise<Retrievable[]>;
+    /** Fetches messages; delegates to the callback supplied at construction. */
+    readonly fetchMessages: () => Message[] | Promise<Message[]>;
+    /** Fetches thoughts; delegates to the callback supplied at construction. */
+    readonly fetchThoughts: () => Thought[] | Promise<Thought[]>;
+    /** Fetches tool calls; delegates to the callback supplied at construction. */
+    readonly fetchToolCalls: () => ToolCall[] | Promise<ToolCall[]>;
+    /** Fetches tools; delegates to the callback supplied at construction. */
+    readonly fetchTools: () => Tool[] | Promise<Tool[]>;
+    /** Refreshes and returns standing instructions. */
+    readonly refreshStandingInstructions: () => (string | Tokenizable)[] | Promise<(string | Tokenizable)[]>;
+    /** Stores a new standing instruction in the local Set and persistence layer. */
+    readonly storeStandingInstruction: (v: string | Tokenizable) => Promise<void>;
+    /** Updates an existing standing instruction in the local Set and persistence layer. */
+    readonly mutateStandingInstruction: (v: string | Tokenizable) => Promise<void>;
+    /** Removes a standing instruction from the local Set and persistence layer. */
+    readonly deleteStandingInstruction: (v: string | Tokenizable) => Promise<void>;
+    /** Stores a new memory in the local Set and persistence layer. */
+    readonly storeMemory: (v: Memory) => Promise<void>;
+    /** Updates an existing memory in the local Set and persistence layer. */
+    readonly mutateMemory: (v: Memory) => Promise<void>;
+    /** Removes a memory from the local Set and persistence layer by ID. */
+    readonly deleteMemory: (id: string) => Promise<void>;
+    /** Stores a new retrievable record in the local Set and persistence layer. */
+    readonly storeRetrievable: (v: Retrievable) => Promise<void>;
+    /** Updates an existing retrievable record in the local Set and persistence layer. */
+    readonly mutateRetrievable: (v: Retrievable) => Promise<void>;
+    /** Removes a retrievable record from the local Set and persistence layer by ID. */
+    readonly deleteRetrievable: (id: string) => Promise<void>;
+    /** Stores a new message in the local Set and persistence layer. */
+    readonly storeMessage: (v: Message) => Promise<void>;
+    /** Updates an existing message in the local Set and persistence layer. */
+    readonly mutateMessage: (v: Message) => Promise<void>;
+    /** Removes a message from the local Set and persistence layer by ID. */
+    readonly deleteMessage: (id: string) => Promise<void>;
+    /** Stores a new thought in the local Set and persistence layer. */
+    readonly storeThought: (v: Thought) => Promise<void>;
+    /** Updates an existing thought in the local Set and persistence layer. */
+    readonly mutateThought: (v: Thought) => Promise<void>;
+    /** Removes a thought from the local Set and persistence layer by ID. */
+    readonly deleteThought: (id: string) => Promise<void>;
+    /** Stores a new tool call in the local Set and persistence layer. */
+    readonly storeToolCall: (v: ToolCall) => Promise<void>;
+    /** Updates an existing tool call in the local Set and persistence layer. */
+    readonly mutateToolCall: (v: ToolCall) => Promise<void>;
+    /** Removes a tool call from the local Set and persistence layer by ID. */
+    readonly deleteToolCall: (id: string) => Promise<void>;
+    /** Emits a `message` hook; fires registered handlers synchronously. */
+    readonly emitMessage: EmitMessageFn;
+    /** Emits a `thought` hook; fires registered handlers synchronously. */
+    readonly emitThought: EmitThoughtFn;
+    /** Emits a `toolCall` hook; fires registered handlers synchronously. */
+    readonly emitToolCall: EmitToolCallFn;
+    /** Emits a `toolExecutionStart` hook; fires registered handlers synchronously. */
+    readonly emitToolExecutionStart: EmitToolExecutionStartFn;
+    /** Emits a `toolExecutionEnd` hook; fires registered handlers synchronously. */
+    readonly emitToolExecutionEnd: EmitToolExecutionEndFn;
+    /** Opens a gate and suspends until it resolves, rejects, times out, or is aborted. */
+    readonly waitFor: OpenGateFn;
+}

package/lib/contracts/media_reader.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Re-openable byte source contract for a Media instance.
+ *
+ * @remarks
+ * Peer to {@link @nhtio/adk!SpoolReader} but tuned for binary streaming rather than line-indexed text.
+ * Each `stream()` call must return a fresh, drainable `ReadableStream` over the same underlying
+ * bytes — implementations model replay: in-memory readers reconstitute the stream from the
+ * buffer, file-backed readers reopen the file handle, HTTP-backed readers re-issue the fetch,
+ * cloud blob readers re-issue the GET. The implementor owns the storage and the cost of keeping
+ * the underlying source addressable. Implementors whose underlying source is genuinely
+ * non-replayable (a raw HTTP body they were handed once) are responsible for caching locally
+ * before constructing the Media.
+ *
+ * Both methods may be synchronous or asynchronous to accommodate both in-memory and I/O-backed
+ * implementations without forcing unnecessary promise overhead on simple cases.
+ */
+export interface MediaReader {
+    /**
+     * Re-opens the underlying byte source and returns a fresh ReadableStream.
+     *
+     * @remarks
+     * Each call yields a new, drainable stream over the same bytes. Render code that needs the
+     * full buffer (e.g. base64-encoding an inline image_url) drains the stream; render code that
+     * can forward the stream (e.g. multipart upload) passes the stream through without buffering.
+     *
+     * @returns A drainable ReadableStream of Uint8Array chunks over the underlying bytes.
+     */
+    stream(): ReadableStream<Uint8Array> | Promise<ReadableStream<Uint8Array>>;
+    /**
+     * Returns the total number of bytes in the underlying data, or `undefined` if unknown.
+     *
+     * @remarks
+     * Used for telemetry, budget checks, and pre-flight provider size validation without forcing
+     * a stream drain. Sources of unknown length may return `undefined` — absence is treated as
+     * "unknown", not "zero".
+     *
+     * @returns The byte length of the underlying data, or `undefined` when unknown.
+     */
+    byteLength(): number | undefined | Promise<number | undefined>;
+}
+/**
+ * Validator schema used to validate a MediaReader value.
+ *
+ * @remarks
+ * Because MediaReader is a structural interface with no associated constructor, validation is
+ * duck-typed: the value must be an object, class instance, or function with `stream` and
+ * `byteLength` present as callable properties. Arity is not enforced.
+ */
+export declare const mediaReaderSchema: import("@nhtio/validation").AnySchema<any>;
+/**
+ * Returns `true` if `value` implements the MediaReader interface.
+ *
+ * @remarks
+ * Duck-typed: checks that `value` is non-null with `stream` and `byteLength` as callable
+ * functions. Does not use `instanceof` — there is no MediaReader constructor.
+ *
+ * @param value - The value to test.
+ * @returns `true` when `value` conforms to the MediaReader interface.
+ */
+export declare const implementsMediaReader: (value: unknown) => value is MediaReader;

package/lib/contracts/spool_reader.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Backing store contract for a {@link @nhtio/adk!SpooledArtifact}.
+ *
+ * @remarks
+ * Implementations may read from memory, a file handle, a network stream, or any other byte
+ * source. The interface is intentionally minimal — the artifact layer handles all higher-level
+ * operations (`head`, `tail`, `grep`, etc.) by composing calls to these three primitives.
+ *
+ * Line indexing is 0-based. Implementations must return `undefined` from {@link SpoolReader.line}
+ * when the index is out of range rather than throwing.
+ *
+ * All three methods may be synchronous or asynchronous to accommodate both in-memory and I/O-
+ * backed implementations without forcing unnecessary promise overhead on simple cases.
+ */
+export interface SpoolReader {
+    /**
+     * Returns the line at the given 0-based index, or `undefined` when out of range.
+     *
+     * @param index - 0-based line index.
+     * @returns The raw line string (without trailing newline), or `undefined`.
+     */
+    line(index: number): string | undefined | Promise<string | undefined>;
+    /**
+     * Returns the total number of bytes in the underlying data.
+     *
+     * @remarks
+     * Used for reporting and token-estimation purposes. Byte length is distinct from character
+     * length for multi-byte encodings.
+     *
+     * @returns The byte length of the underlying data.
+     */
+    byteLength(): number | Promise<number>;
+    /**
+     * Returns the total number of lines in the underlying data.
+     *
+     * @remarks
+     * Required so consumers know when to stop iterating; the line count must remain stable for the
+     * lifetime of the reader.
+     *
+     * @returns The total line count.
+     */
+    lineCount(): number | Promise<number>;
+    /**
+     * Returns the full underlying content as a single decoded string, byte-faithful to the source.
+     *
+     * @remarks
+     * Unlike {@link SpoolReader.line}, this method preserves trailing newlines and any non-`\n`
+     * line terminators (e.g. `\r\n`) present in the original bytes. It is the primitive that
+     * powers `SpooledArtifact.asString()` — the round-trip-faithful alternative to assembling
+     * the artifact body from per-line reads.
+     *
+     * Implementations should make this O(n) in the size of the underlying data and may cache the
+     * result if the read source is durable. Streaming implementations may choose not to cache.
+     *
+     * @returns The full underlying content as a single string.
+     */
+    readAll(): string | Promise<string>;
+}
+/**
+ * Validator schema used to validate a {@link SpoolReader} value.
+ *
+ * @remarks
+ * Because `SpoolReader` is a structural interface with no associated constructor, validation is
+ * duck-typed: the value must be an object, class instance, or function with `line`, `byteLength`,
+ * and `lineCount` present as callable properties. Arity is not enforced — implementations may add
+ * optional parameters beyond the contract.
+ */
+export declare const spoolReaderSchema: import("@nhtio/validation").AnySchema<any>;
+/**
+ * Returns `true` if `value` implements the {@link SpoolReader} interface.
+ *
+ * @remarks
+ * Duck-typed: checks that `value` is non-null with `line`, `byteLength`, `lineCount`, and
+ * `readAll` as callable functions. Does not use `instanceof` — there is no `SpoolReader`
+ * constructor.
+ *
+ * @param value - The value to test.
+ * @returns `true` when `value` conforms to the {@link SpoolReader} interface.
+ */
+export declare const implementsSpoolReader: (value: unknown) => value is SpoolReader;

package/lib/contracts/spooled_artifact_constructor.d.ts

@@ -0,0 +1,38 @@
+import type { SpooledArtifact } from "../classes/spooled_artifact";
+/**
+ * Constructor signature for any {@link @nhtio/adk!SpooledArtifact} (the class itself or a subclass).
+ *
+ * @remarks
+ * Re-declared here at the contract level so consumers — and the `Tool.artifactConstructor`
+ * resolver validator in particular — can talk about the constructor shape without value-importing
+ * the {@link @nhtio/adk!SpooledArtifact} class (which would close the `tool.ts` ↔ `spooled_artifact.ts` ↔
+ * `artifact_tool.ts` module cycle at load time and TDZ-crash `ArtifactTool extends Tool`).
+ *
+ * @typeParam A - The {@link @nhtio/adk!SpooledArtifact} subtype the constructor produces.
+ */
+export type SpooledArtifactConstructorLike<A extends SpooledArtifact = SpooledArtifact> = new (...args: any[]) => A;
+/**
+ * Validator schema used to validate a {@link SpooledArtifactConstructorLike} value.
+ *
+ * @remarks
+ * Because the validator is invoked at validate-time (not at module-load), it is safe to inspect
+ * the constructor's prototype here. The check is duck-typed: the value must be a function whose
+ * `prototype` carries every canonical artifact instance method (`head`, `tail`, `grep`, `cat`,
+ * `byteLength`, `lineCount`, `estimateTokens`). This mirrors {@link spoolReaderSchema}'s
+ * cross-realm-safe duck-type pattern — `instanceof SpooledArtifact` would be tighter but would
+ * force a value-import of the class and reopen the module cycle.
+ */
+export declare const spooledArtifactConstructorSchema: import("@nhtio/validation").AnySchema<any>;
+/**
+ * Returns `true` if `value` is a constructor whose prototype carries every canonical
+ * {@link @nhtio/adk!SpooledArtifact} instance method.
+ *
+ * @remarks
+ * Duck-typed; does not use `instanceof SpooledArtifact`. Used by the `Tool.artifactConstructor`
+ * resolver validator and any other site that needs to recognise a `SpooledArtifact`-like
+ * constructor without pulling the class into its module-load graph.
+ *
+ * @param value - The value to test.
+ * @returns `true` when `value` is a `SpooledArtifact`-shaped constructor.
+ */
+export declare const implementsSpooledArtifactConstructor: (value: unknown) => value is SpooledArtifactConstructorLike;

package/lib/contracts/turn_runner_config.d.ts

@@ -0,0 +1,101 @@
+import { Tool } from "../classes/tool";
+import type { TurnPipelineMiddlewareFn } from "../types/turn_runner";
+import type { DispatchPipelineMiddlewareFn, DispatchExecutorFn } from "../types/dispatch_runner";
+import type { MemoryRetrievalFn, MessageRetrievalFn, ThoughtRetrievalFn, ToolCallRetrievalFn, ToolsRetrievalFn, StandingInstructionsRefreshFn, StandingInstructionStoreFn, StandingInstructionMutateFn, StandingInstructionDeleteFn, MemoryStoreFn, MemoryMutateFn, MemoryDeleteFn, RetrievableRetrievalFn, RetrievableStoreFn, RetrievableMutateFn, RetrievableDeleteFn, MessageStoreFn, MessageMutateFn, MessageDeleteFn, ThoughtStoreFn, ThoughtMutateFn, ThoughtDeleteFn, ToolCallStoreFn, ToolCallMutateFn, ToolCallDeleteFn } from "./turn_runner_context";
+/**
+ * Configuration supplied to {@link @nhtio/adk!TurnRunner} at construction time.
+ *
+ * @remarks
+ * Validated against `turnRunnerConfigSchema` at construction — a misconfigured runner throws
+ * immediately rather than failing on the first turn.
+ *
+ * All fetch and mutation callbacks are required: they are injected into each {@link @nhtio/adk!TurnContext}
+ * so middleware can call fetch, refresh, and persistence methods directly on the context without
+ * coupling to the runner.
+ *
+ * `tools` is optional at the caller level and defaults to `[]` after schema resolution — a runner
+ * with no baseline tools is valid.
+ */
+export interface TurnRunnerConfig {
+    /** Performs the LLM API/SDK call for each iteration of the dispatch loop; receives the active {@link @nhtio/adk!DispatchContext} and an {@link @nhtio/adk!DispatchExecutorHelpers} object for managing per-id stream state. */
+    executorCallback: DispatchExecutorFn;
+    /** Called once per turn to supply memories; receives the active {@link @nhtio/adk!TurnContext}. */
+    fetchMemoriesCallback: MemoryRetrievalFn;
+    /** Called once per turn to supply conversation history; receives the active {@link @nhtio/adk!TurnContext}. */
+    fetchMessagesCallback: MessageRetrievalFn;
+    /** Called once per turn to supply thought traces; receives the active {@link @nhtio/adk!TurnContext}. */
+    fetchThoughtsCallback: ThoughtRetrievalFn;
+    /** Called once per turn to supply tool call records; receives the active {@link @nhtio/adk!TurnContext}. */
+    fetchToolCallsCallback: ToolCallRetrievalFn;
+    /** Called to supply available tools; receives the active {@link @nhtio/adk!TurnContext}. */
+    fetchToolsCallback: ToolsRetrievalFn;
+    /** Called to refresh and return standing instructions; receives the active {@link @nhtio/adk!TurnContext}. */
+    refreshStandingInstructionsCallback: StandingInstructionsRefreshFn;
+    /** Persists a new standing instruction. */
+    storeStandingInstructionCallback: StandingInstructionStoreFn;
+    /** Updates an existing standing instruction in the persistence layer. */
+    mutateStandingInstructionCallback: StandingInstructionMutateFn;
+    /** Removes a standing instruction from the persistence layer. */
+    deleteStandingInstructionCallback: StandingInstructionDeleteFn;
+    /** Persists a new memory. */
+    storeMemoryCallback: MemoryStoreFn;
+    /** Updates an existing memory in the persistence layer. */
+    mutateMemoryCallback: MemoryMutateFn;
+    /** Removes a memory from the persistence layer by ID. */
+    deleteMemoryCallback: MemoryDeleteFn;
+    /** Called once per turn to supply retrievable (RAG) records; receives the active {@link @nhtio/adk!TurnContext}. */
+    fetchRetrievablesCallback: RetrievableRetrievalFn;
+    /** Persists a new retrievable record. */
+    storeRetrievableCallback: RetrievableStoreFn;
+    /** Updates an existing retrievable record in the persistence layer. */
+    mutateRetrievableCallback: RetrievableMutateFn;
+    /** Removes a retrievable record from the persistence layer by ID. */
+    deleteRetrievableCallback: RetrievableDeleteFn;
+    /** Persists a new message. */
+    storeMessageCallback: MessageStoreFn;
+    /** Updates an existing message in the persistence layer. */
+    mutateMessageCallback: MessageMutateFn;
+    /** Removes a message from the persistence layer by ID. */
+    deleteMessageCallback: MessageDeleteFn;
+    /** Persists a new thought. */
+    storeThoughtCallback: ThoughtStoreFn;
+    /** Updates an existing thought in the persistence layer. */
+    mutateThoughtCallback: ThoughtMutateFn;
+    /** Removes a thought from the persistence layer by ID. */
+    deleteThoughtCallback: ThoughtDeleteFn;
+    /** Persists a new tool call. */
+    storeToolCallCallback: ToolCallStoreFn;
+    /** Updates an existing tool call in the persistence layer. */
+    mutateToolCallCallback: ToolCallMutateFn;
+    /** Removes a tool call from the persistence layer by ID. */
+    deleteToolCallCallback: ToolCallDeleteFn;
+    /** Baseline tools available on every turn. Middleware may trim or extend this per-turn via `ctx.tools`. Defaults to `[]`. */
+    tools?: Tool[];
+    /** Turn-level input middleware, executed in order against the {@link @nhtio/adk!TurnContext} before the LLM dispatch. Defaults to `[]`. */
+    turnInputPipeline?: TurnPipelineMiddlewareFn[];
+    /** Turn-level output middleware, executed in order against the {@link @nhtio/adk!TurnContext} after the LLM dispatch resolves successfully. Defaults to `[]`. */
+    turnOutputPipeline?: TurnPipelineMiddlewareFn[];
+    /** LLM-iteration input middleware, executed in order against the {@link @nhtio/adk!DispatchContext} before the executor on each iteration. Defaults to `[]`. */
+    dispatchInputPipeline?: DispatchPipelineMiddlewareFn[];
+    /** LLM-iteration output middleware, executed in order against the {@link @nhtio/adk!DispatchContext} after the executor on each iteration. Defaults to `[]`. */
+    dispatchOutputPipeline?: DispatchPipelineMiddlewareFn[];
+}
+/**
+ * Fully-resolved {@link TurnRunnerConfig} after schema validation.
+ *
+ * @remarks
+ * All optional fields are guaranteed present (e.g. `tools` defaults to `[]`). The runner stores
+ * this type internally so field access never needs to guard for undefined.
+ */
+export type ResolvedTurnRunnerConfig = Required<TurnRunnerConfig>;
+/**
+ * Validator schema used to validate a {@link TurnRunnerConfig} at {@link @nhtio/adk!TurnRunner} construction time.
+ *
+ * @remarks
+ * Validates that all callbacks are functions of the correct arity, and that `tools` — when
+ * provided — is an array of valid {@link @nhtio/adk!Tool} instances. Defaults `tools` to `[]`.
+ *
+ * Throws {@link @nhtio/adk!E_INVALID_TURN_RUNNER_CONFIG} (via the {@link @nhtio/adk!TurnRunner} constructor) when
+ * validation fails.
+ */
+export declare const turnRunnerConfigSchema: import("@nhtio/validation").ObjectSchema<TurnRunnerConfig>;