@nhtio/adk 0.1.0-master-f0aa531d

package/lib/contracts/turn_runner_context.d.ts

@@ -0,0 +1,267 @@
+import { Registry } from "../classes/registry";
+import { Tokenizable } from "../classes/tokenizable";
+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 { ToolRegistry } from "../classes/tool_registry";
+import type { EmitMessageFn, EmitThoughtFn, EmitToolCallFn, EmitToolExecutionEndFn, EmitToolExecutionStartFn, OpenGateFn } from "../types/turn_runner";
+/**
+ * Plain input object supplied to {@link TurnContext} at construction time.
+ *
+ * @remarks
+ * Validated against `turnContextSchema` before the `TurnContext` instance is created.
+ * Fields will grow as the turn execution model takes shape (e.g. input message, tool
+ * definitions, model client config).
+ */
+export interface RawTurnContext {
+    /** `AbortController` whose signal can be used to cancel the turn mid-flight. */
+    turnAbortController: AbortController;
+    /** A registry for arbitrary additional data to be added to the context as needed; initially empty. */
+    stash?: Record<string, unknown>;
+    /** The system prompt guiding the agent's behavior for this turn. */
+    systemPrompt: string | Tokenizable;
+    /** Standing instructions for the agent, applied to every turn. */
+    standingInstructions: (string | Tokenizable)[];
+}
+/**
+ * A fully-resolved {@link RawTurnContext} where all optional fields have been filled in by the
+ * schema (e.g. `stash` defaulted to `{}`).
+ *
+ * @remarks
+ * This is the shape returned by `turnContextSchema` after validation — use it wherever a
+ * guaranteed-present context is needed rather than the raw caller-supplied input.
+ */
+export type ResolvedTurnContext = Required<RawTurnContext>;
+/**
+ * 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.
+ */
+export declare const turnContextSchema: import("@nhtio/validation").ObjectSchema<RawTurnContext>;
+/**
+ * A function that retrieves the memories relevant to the current turn.
+ *
+ * @remarks
+ * Receives the active {@link TurnContext} so implementations can filter or rank memories
+ * based on turn-specific state (e.g. the system prompt, standing instructions, or stash).
+ * May be synchronous or asynchronous.
+ */
+export type MemoryRetrievalFn = (ctx: TurnContext) => Memory[] | Promise<Memory[]>;
+/**
+ * A function that retrieves the retrievable (RAG) records relevant to the current turn.
+ *
+ * @remarks
+ * Receives the active {@link TurnContext} so implementations can rank, filter, or compose
+ * retrieval results against the turn-specific state (system prompt, standing instructions, etc.).
+ * The retrieval middleware that produces these records is responsible for assigning each one's
+ * `trustTier` — batteries MUST NOT auto-classify retrieved content.
+ * May be synchronous or asynchronous.
+ */
+export type RetrievableRetrievalFn = (ctx: TurnContext) => Retrievable[] | Promise<Retrievable[]>;
+/**
+ * A function that retrieves the conversation messages relevant to the current turn.
+ *
+ * @remarks
+ * Receives the active {@link TurnContext} so implementations can apply turn-aware filtering or
+ * windowing. Returns only `user` and `assistant` {@link @nhtio/adk!Message} entries — system instructions
+ * and tool results are not part of the persisted message history.
+ * May be synchronous or asynchronous.
+ */
+export type MessageRetrievalFn = (ctx: TurnContext) => Message[] | Promise<Message[]>;
+/**
+ * A function that retrieves the thought traces relevant to the current turn.
+ *
+ * @remarks
+ * Receives the active {@link TurnContext} so implementations can apply turn-aware filtering or
+ * attribution (e.g. filtering to a specific agent's identity in multi-agent conversations).
+ * May be synchronous or asynchronous.
+ */
+export type ThoughtRetrievalFn = (ctx: TurnContext) => Thought[] | Promise<Thought[]>;
+/**
+ * A function that retrieves the tool call records relevant to the current turn.
+ *
+ * @remarks
+ * Receives the active {@link TurnContext} so implementations can filter by completion state,
+ * agent identity, or any other turn-specific criteria.
+ * May be synchronous or asynchronous.
+ */
+export type ToolCallRetrievalFn = (ctx: TurnContext) => ToolCall[] | Promise<ToolCall[]>;
+/**
+ * A function that retrieves the tools available for the current turn.
+ *
+ * @remarks
+ * Receives the active {@link TurnContext} so implementations can apply turn-aware filtering
+ * (e.g. RBAC scopes, feature flags). May be synchronous or asynchronous.
+ */
+export type ToolsRetrievalFn = (ctx: TurnContext) => Tool[] | Promise<Tool[]>;
+/**
+ * A function that refreshes and returns the standing instructions for the current turn.
+ *
+ * @remarks
+ * Called to re-derive standing instructions mid-turn when they may have changed.
+ * May be synchronous or asynchronous.
+ */
+export type StandingInstructionsRefreshFn = (ctx: TurnContext) => (string | Tokenizable)[] | Promise<(string | Tokenizable)[]>;
+/** Stores a new standing instruction in the persistence layer. */
+export type StandingInstructionStoreFn = (ctx: TurnContext, v: string | Tokenizable) => void | Promise<void>;
+/** Updates an existing standing instruction in the persistence layer. */
+export type StandingInstructionMutateFn = (ctx: TurnContext, v: string | Tokenizable) => void | Promise<void>;
+/** Removes a standing instruction from the persistence layer. */
+export type StandingInstructionDeleteFn = (ctx: TurnContext, v: string | Tokenizable) => void | Promise<void>;
+/** Stores a new memory in the persistence layer. */
+export type MemoryStoreFn = (ctx: TurnContext, v: Memory) => void | Promise<void>;
+/** Updates an existing memory in the persistence layer. */
+export type MemoryMutateFn = (ctx: TurnContext, v: Memory) => void | Promise<void>;
+/** Removes a memory from the persistence layer by ID. */
+export type MemoryDeleteFn = (ctx: TurnContext, id: string) => void | Promise<void>;
+/** Stores a new retrievable record in the persistence layer. */
+export type RetrievableStoreFn = (ctx: TurnContext, v: Retrievable) => void | Promise<void>;
+/** Updates an existing retrievable record in the persistence layer. */
+export type RetrievableMutateFn = (ctx: TurnContext, v: Retrievable) => void | Promise<void>;
+/** Removes a retrievable record from the persistence layer by ID. */
+export type RetrievableDeleteFn = (ctx: TurnContext, id: string) => void | Promise<void>;
+/** Stores a new message in the persistence layer. */
+export type MessageStoreFn = (ctx: TurnContext, v: Message) => void | Promise<void>;
+/** Updates an existing message in the persistence layer. */
+export type MessageMutateFn = (ctx: TurnContext, v: Message) => void | Promise<void>;
+/** Removes a message from the persistence layer by ID. */
+export type MessageDeleteFn = (ctx: TurnContext, id: string) => void | Promise<void>;
+/** Stores a new thought in the persistence layer. */
+export type ThoughtStoreFn = (ctx: TurnContext, v: Thought) => void | Promise<void>;
+/** Updates an existing thought in the persistence layer. */
+export type ThoughtMutateFn = (ctx: TurnContext, v: Thought) => void | Promise<void>;
+/** Removes a thought from the persistence layer by ID. */
+export type ThoughtDeleteFn = (ctx: TurnContext, id: string) => void | Promise<void>;
+/** Stores a new tool call in the persistence layer. */
+export type ToolCallStoreFn = (ctx: TurnContext, v: ToolCall) => void | Promise<void>;
+/** Updates an existing tool call in the persistence layer. */
+export type ToolCallMutateFn = (ctx: TurnContext, v: ToolCall) => void | Promise<void>;
+/** Removes a tool call from the persistence layer by ID. */
+export type ToolCallDeleteFn = (ctx: TurnContext, id: string) => void | Promise<void>;
+/**
+ * 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.
+ */
+export declare class TurnContext {
+    #private;
+    /**
+     * 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: unknown): value is TurnContext;
+    /** Unique identifier for this turn, generated as a UUIDv6 at construction time. */
+    readonly id: string;
+    /** `true` when the turn's `AbortController` signal has fired. */
+    readonly aborted: boolean;
+    /** The `AbortSignal` from the turn's `AbortController`. */
+    readonly abortSignal: AbortSignal;
+    /**
+     * Aborts the turn's `AbortController` with the supplied reason. Middleware should call this
+     * when refusing the turn — the runner reads `aborted` between every stage and short-circuits
+     * cleanly: `turnEnd` still fires, no `error` event is emitted, and during dispatch
+     * `dispatchEnd.status === 'aborted'` carries the operational signal.
+     */
+    readonly abort: (reason?: unknown) => void;
+    /** Arbitrary key-value store that middleware can read and write across pipeline steps. */
+    readonly stash: Registry;
+    /** The system prompt guiding the agent's behaviour for this turn. */
+    readonly systemPrompt: Tokenizable;
+    /** Standing instructions applied to every turn, in insertion order. */
+    readonly standingInstructions: Set<Tokenizable>;
+    /** Memories loaded for this turn; populated by middleware after calling `fetchMemories()`. */
+    readonly turnMemories: Set<Memory>;
+    /** Retrievable records loaded for this turn; populated by middleware after calling `fetchRetrievables()`. */
+    readonly turnRetrievables: Set<Retrievable>;
+    /** Conversation messages loaded for this turn; populated by middleware after calling `fetchMessages()`. */
+    readonly turnMessages: Set<Message>;
+    /** Thought traces loaded for this turn; populated by middleware after calling `fetchThoughts()`. */
+    readonly turnThoughts: Set<Thought>;
+    /** Tool call records loaded for this turn; populated by middleware after calling `fetchToolCalls()`. */
+    readonly turnToolCalls: Set<ToolCall>;
+    /** Fetches memories relevant to this turn; delegates to the callback supplied at construction. */
+    readonly fetchMemories: () => Memory[] | Promise<Memory[]>;
+    /** Fetches conversation messages relevant to this turn; delegates to the callback supplied at construction. */
+    readonly fetchMessages: () => Message[] | Promise<Message[]>;
+    /** Fetches thought traces relevant to this turn; delegates to the callback supplied at construction. */
+    readonly fetchThoughts: () => Thought[] | Promise<Thought[]>;
+    /** Fetches tool call records relevant to this turn; delegates to the callback supplied at construction. */
+    readonly fetchToolCalls: () => ToolCall[] | Promise<ToolCall[]>;
+    /** Fetches tools available for this turn; delegates to the callback supplied at construction. */
+    readonly fetchTools: () => Tool[] | Promise<Tool[]>;
+    /** Refreshes and returns the standing instructions; delegates to the callback supplied at construction. */
+    readonly refreshStandingInstructions: () => (string | Tokenizable)[] | Promise<(string | Tokenizable)[]>;
+    /** Stores a new standing instruction in the persistence layer. */
+    readonly storeStandingInstruction: (v: string | Tokenizable) => void | Promise<void>;
+    /** Updates an existing standing instruction in the persistence layer. */
+    readonly mutateStandingInstruction: (v: string | Tokenizable) => void | Promise<void>;
+    /** Removes a standing instruction from the persistence layer. */
+    readonly deleteStandingInstruction: (v: string | Tokenizable) => void | Promise<void>;
+    /** Stores a new memory in the persistence layer. */
+    readonly storeMemory: (v: Memory) => void | Promise<void>;
+    /** Updates an existing memory in the persistence layer. */
+    readonly mutateMemory: (v: Memory) => void | Promise<void>;
+    /** Removes a memory from the persistence layer by ID. */
+    readonly deleteMemory: (id: string) => void | Promise<void>;
+    /** Fetches retrievable records relevant to this turn; delegates to the callback supplied at construction. */
+    readonly fetchRetrievables: () => Retrievable[] | Promise<Retrievable[]>;
+    /** Stores a new retrievable record in the persistence layer. */
+    readonly storeRetrievable: (v: Retrievable) => void | Promise<void>;
+    /** Updates an existing retrievable record in the persistence layer. */
+    readonly mutateRetrievable: (v: Retrievable) => void | Promise<void>;
+    /** Removes a retrievable record from the persistence layer by ID. */
+    readonly deleteRetrievable: (id: string) => void | Promise<void>;
+    /** Stores a new message in the persistence layer. */
+    readonly storeMessage: (v: Message) => void | Promise<void>;
+    /** Updates an existing message in the persistence layer. */
+    readonly mutateMessage: (v: Message) => void | Promise<void>;
+    /** Removes a message from the persistence layer by ID. */
+    readonly deleteMessage: (id: string) => void | Promise<void>;
+    /** Stores a new thought in the persistence layer. */
+    readonly storeThought: (v: Thought) => void | Promise<void>;
+    /** Updates an existing thought in the persistence layer. */
+    readonly mutateThought: (v: Thought) => void | Promise<void>;
+    /** Removes a thought from the persistence layer by ID. */
+    readonly deleteThought: (id: string) => void | Promise<void>;
+    /** Stores a new tool call in the persistence layer. */
+    readonly storeToolCall: (v: ToolCall) => void | Promise<void>;
+    /** Updates an existing tool call in the persistence layer. */
+    readonly mutateToolCall: (v: ToolCall) => void | Promise<void>;
+    /** Removes a tool call from the persistence layer by ID. */
+    readonly deleteToolCall: (id: string) => void | Promise<void>;
+    /** Emits a `message` event on the runner; may be called at any point during the turn. */
+    readonly emitMessage: EmitMessageFn;
+    /** Emits a `thought` event on the runner; may be called at any point during the turn. */
+    readonly emitThought: EmitThoughtFn;
+    /** Emits a `toolCall` event on the runner; may be called at any point during the turn. */
+    readonly emitToolCall: EmitToolCallFn;
+    /** Emits a `toolExecutionStart` event on the observability bus; forwarded from `DispatchContext` by `DispatchRunner` when a tool is invoked inside a dispatch. */
+    readonly emitToolExecutionStart: EmitToolExecutionStartFn;
+    /** Emits a `toolExecutionEnd` event on the observability bus; forwarded from `DispatchContext` by `DispatchRunner` when a tool finishes executing inside a dispatch. */
+    readonly emitToolExecutionEnd: EmitToolExecutionEndFn;
+    /** Opens a turn gate and suspends until it resolves, rejects, times out, or is aborted. */
+    readonly waitFor: OpenGateFn;
+    /** Turn-scoped tool registry constructed from the runner's baseline tools; middleware may trim or extend it. */
+    readonly tools: ToolRegistry;
+}

package/lib/dispatch_runner.d.ts

@@ -0,0 +1,98 @@
+import { TurnContext } from "./contracts/turn_runner_context";
+import type { RawDispatchContext } from "./contracts/dispatch_context";
+import type { DispatchPipelineMiddlewareFn, DispatchExecutorFn, DispatchRunnerFunctionalHookRegistrations, DispatchRunnerObservabilityHookRegistrations } from "./types/dispatch_runner";
+/**
+ * Plain input object supplied to {@link DispatchRunner.dispatch}.
+ *
+ * @remarks
+ * Exactly one of `source` or `raw` is required:
+ *
+ * - `source` — switches to the **derived path**. The runner snapshots primitives from the
+ *   provided {@link @nhtio/adk!TurnContext}, wires all fetch/refresh/mutation callbacks to delegate to it,
+ *   forwards emits back to its buses, and bubbles mutations to its Sets at the end of every
+ *   iteration.
+ *
+ * - `raw` — switches to the **standalone path**. The runner constructs an {@link @nhtio/adk!DispatchContext}
+ *   directly from the provided raw input. No parent relationship exists; mutations are not bubbled.
+ *
+ * The `executor` is the user-provided callback that performs the actual LLM API call between the
+ * input and output middleware pipelines on every iteration.
+ */
+export interface RawDispatchRunnerInput {
+    /** Source {@link @nhtio/adk!TurnContext} to derive the execution context from. Mutually exclusive with `raw`. */
+    source?: TurnContext;
+    /** Raw input for a standalone {@link @nhtio/adk!DispatchContext}. Mutually exclusive with `source`. */
+    raw?: Omit<RawDispatchContext, 'hooks'>;
+    /** User-provided callback that makes the LLM API call. Invoked between input and output pipelines on every iteration. */
+    executor: DispatchExecutorFn;
+    /** Input middleware functions, executed in order before the executor on every iteration. */
+    turnInputPipeline?: DispatchPipelineMiddlewareFn[];
+    /** Output middleware functions, executed in order after the executor on every iteration. */
+    turnOutputPipeline?: DispatchPipelineMiddlewareFn[];
+    /** Optional functional hook registrations: message, thought, toolCall. */
+    hooks?: DispatchRunnerFunctionalHookRegistrations;
+    /** Optional observability hook registrations: lifecycle events + tool execution + error. */
+    observers?: DispatchRunnerObservabilityHookRegistrations;
+}
+/**
+ * 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.
+ */
+declare const CONSTRUCT_TOKEN: unique symbol;
+export declare class DispatchRunner {
+    #private;
+    constructor(token: typeof CONSTRUCT_TOKEN, sourceCtx: TurnContext | undefined, turnInputPipeline: DispatchPipelineMiddlewareFn[], turnOutputPipeline: DispatchPipelineMiddlewareFn[], hooks: DispatchRunnerFunctionalHookRegistrations | undefined, observers: DispatchRunnerObservabilityHookRegistrations | undefined);
+    /**
+     * 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: unknown): value is 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 dispatch(input: RawDispatchRunnerInput): Promise<void>;
+}
+export {};