@nhtio/adk 0.1.0-master-f0aa531d

package/lib/types/turn_runner.d.ts

@@ -0,0 +1,322 @@
+import type { DateTime } from 'luxon';
+import type { NextFn } from '@nhtio/middleware';
+import type { BaseException } from "../classes/base_exception";
+import type { TurnGate, RawTurnGate } from "../classes/turn_gate";
+import type { TurnContext } from "../contracts/turn_runner_context";
+import type { EventMap, Key, Listener } from '@nhtio/tiny-typed-emitter';
+import type { DispatchStartEvent, DispatchEndEvent, IterationStartEvent, IterationEndEvent, LogEvent } from "./dispatch_runner";
+/**
+ * Middleware function signature for the input and output pipelines in a {@link @nhtio/adk!TurnRunner}.
+ *
+ * @param ctx - The mutable {@link @nhtio/adk!TurnContext} for the current turn.
+ * @param next - Callback to advance to the next middleware in the chain.
+ */
+export type TurnPipelineMiddlewareFn = (ctx: TurnContext, next: NextFn) => void | Promise<void>;
+/**
+ * A unit of streamable content emitted during a turn.
+ *
+ * @remarks
+ * Each emission represents either a visible assistant message or an internal reasoning trace.
+ * `aDelta` carries the incremental text since the last emission; `full` is the accumulated text
+ * so far. `isComplete` is `true` on the final emission for a given `id`.
+ */
+export interface TurnStreamableContent {
+    /** Stable identifier for this content stream; groups deltas from the same generation. */
+    id: string;
+    /** Timestamp when this content stream was first created. */
+    createdAt: DateTime;
+    /** Timestamp of the most recent delta received for this stream. */
+    updatedAt: DateTime;
+    /** Full accumulated text received so far for this stream. */
+    full: string;
+    /** Incremental text added since the previous emission. */
+    aDelta: string;
+    /** `true` on the final chunk for this `id`; subsequent emissions will use a new `id`. */
+    isComplete: boolean;
+    /** Timestamp when the stream completed. Absent until `isComplete` is `true`. */
+    completedAt?: DateTime;
+}
+/**
+ * A tool call invocation emitted during a turn, including its result once available.
+ *
+ * @remarks
+ * Emitted at least once when the model requests a tool call. The same `id` is re-emitted with
+ * `results` populated and `isComplete` set to `true` after the tool has been executed. If
+ * execution fails, `isError` is `true` and `results` contains the error detail.
+ */
+export interface TurnToolCallContent {
+    /** Stable identifier for this tool call; correlates the initial request with its result. */
+    id: string;
+    /** Name of the tool the model has requested. */
+    tool: string;
+    /** Arguments the model supplied for the tool call. */
+    args: unknown;
+    /** Integrity checksum over `tool` and `args`; can be used to detect tampering before execution. */
+    checksum: string;
+    /** Timestamp when this tool call was first emitted. */
+    createdAt: DateTime;
+    /** Timestamp of the most recent update to this tool call (e.g. when results arrived). */
+    updatedAt: DateTime;
+    /**
+     * Result returned by the tool, or error detail when `isError` is `true`. Absent until execution
+     * completes.
+     *
+     * @remarks
+     * Shape depends on the underlying tool kind. For a normal {@link @nhtio/adk!Tool}
+     * call, this carries one or more {@link @nhtio/adk!SpooledArtifact}
+     * instances (single artifact or `SpooledArtifact[]`) wrapping the bytes returned by the handler,
+     * or one or more {@link @nhtio/adk!Media} instances (single `Media` or
+     * `Media[]`) when the handler took the explicit-modality return path. For an
+     * {@link @nhtio/adk!ArtifactTool} call, this is the raw string the
+     * handler emitted (`Tokenizable.toString()`-equivalent) — already the model-visible answer.
+     * Type stays `unknown` to keep this event payload narrow; the underlying
+     * `ToolCall.results` is `Tokenizable | SpooledArtifact | SpooledArtifact[] | Media | Media[]`.
+     *
+     * @see {@link @nhtio/adk!ToolCall.results}
+     */
+    results?: unknown;
+    /** `true` once the tool call has finished (successfully or not). */
+    isComplete: boolean;
+    /** `true` when the tool execution produced an error; inspect `results` for detail. */
+    isError: boolean;
+    /** Timestamp when the tool call completed (successfully or not). */
+    completedAt?: DateTime;
+}
+/**
+ * Payload emitted when a turn begins.
+ */
+export interface TurnStartEvent {
+    /** The unique ID of the turn that started. */
+    turnId: string;
+    /** When the turn started. */
+    startedAt: DateTime;
+}
+/**
+ * Payload emitted when a turn ends.
+ */
+export interface TurnEndEvent {
+    /** The unique ID of the turn that ended. */
+    turnId: string;
+    /** When the turn started. */
+    startedAt: DateTime;
+    /** When the turn ended. */
+    endedAt: DateTime;
+    /** Duration of the turn in milliseconds. */
+    durationMs: number;
+}
+/**
+ * Payload emitted on the observability bus when a tool's executor begins executing the handler.
+ *
+ * @remarks
+ * Fired after arg validation passes and immediately before the handler is called.
+ * `callId` correlates the event with the {@link @nhtio/adk!ToolCall} record if one is being tracked. Fires
+ * for both {@link @nhtio/adk!Tool} and
+ * {@link @nhtio/adk!ArtifactTool} invocations — the payload is identical.
+ */
+export interface ToolExecutionStartEvent {
+    /** Name of the tool being executed. */
+    toolName: string;
+    /** ID of the turn in which the tool is being executed. */
+    turnId: string;
+    /** Correlates with the associated ToolCall id, if known. Empty string when not provided. */
+    callId: string;
+    /** The validated arguments that will be passed to the handler. */
+    args: unknown;
+    /** When execution started. */
+    startedAt: DateTime;
+}
+/**
+ * Payload emitted on the observability bus when a tool's executor finishes (successfully or not).
+ *
+ * @remarks
+ * Fired after the handler returns or throws. When `isError` is `true`, the handler threw and the
+ * error has been wrapped in {@link @nhtio/adk!E_TOOL_DOWNSTREAM_ERROR}. Fires for both
+ * {@link @nhtio/adk!Tool} and
+ * {@link @nhtio/adk!ArtifactTool} invocations — the payload is identical.
+ */
+export interface ToolExecutionEndEvent {
+    /** Name of the tool that was executed. */
+    toolName: string;
+    /** ID of the turn in which the tool was executed. */
+    turnId: string;
+    /** Correlates with the associated ToolCall id, if known. Empty string when not provided. */
+    callId: string;
+    /** When execution started. */
+    startedAt: DateTime;
+    /** When execution ended. */
+    endedAt: DateTime;
+    /** Duration of the execution in milliseconds. */
+    durationMs: number;
+    /** `true` when the handler threw an error; the rejection reason is {@link @nhtio/adk!E_TOOL_DOWNSTREAM_ERROR}. */
+    isError: boolean;
+}
+/**
+ * Payload emitted when a {@link @nhtio/adk!TurnGate} settles (resolved, rejected, aborted, or timed out).
+ */
+export interface TurnGateClosedEvent {
+    /** ID of the gate that settled. */
+    gateId: string;
+    /** ID of the turn that owned the gate. */
+    turnId: string;
+    /** How the gate settled. */
+    result: 'resolved' | 'rejected' | 'aborted' | 'timeout';
+    /** When the gate settled. */
+    settledAt: DateTime;
+}
+/**
+ * A function that emits a `message` event on the {@link @nhtio/adk!TurnRunner}.
+ *
+ * @remarks
+ * Injected into {@link @nhtio/adk!TurnContext} so middleware can surface streaming message chunks without
+ * holding a reference to the runner or its emitter.
+ */
+export type EmitMessageFn = (content: TurnStreamableContent) => void;
+/**
+ * A function that emits a `thought` event on the {@link @nhtio/adk!TurnRunner}.
+ *
+ * @remarks
+ * Injected into {@link @nhtio/adk!TurnContext} so middleware can surface reasoning trace chunks without
+ * holding a reference to the runner or its emitter.
+ */
+export type EmitThoughtFn = (content: TurnStreamableContent) => void;
+/**
+ * A function that emits a `toolCall` event on the {@link @nhtio/adk!TurnRunner}.
+ *
+ * @remarks
+ * Injected into {@link @nhtio/adk!TurnContext} so middleware can surface tool call lifecycle events —
+ * both the initial request and the settled result — without holding a reference to the runner.
+ */
+export type EmitToolCallFn = (content: TurnToolCallContent) => void;
+/**
+ * A function that emits a `toolExecutionStart` event on the {@link @nhtio/adk!TurnRunner} observability bus.
+ *
+ * @remarks
+ * Injected into both {@link @nhtio/adk!TurnContext} and `DispatchContext` so `Tool.executor()` can emit
+ * lifecycle events without holding a reference to the runner or its emitter. Tool execution
+ * happens inside an LLM dispatch loop; `DispatchContext` is the canonical context the tool
+ * handler receives.
+ */
+export type EmitToolExecutionStartFn = (event: ToolExecutionStartEvent) => void;
+/**
+ * A function that emits a `toolExecutionEnd` event on the {@link @nhtio/adk!TurnRunner} observability bus.
+ *
+ * @remarks
+ * Injected into both {@link @nhtio/adk!TurnContext} and `DispatchContext` so `Tool.executor()` can emit
+ * lifecycle events without holding a reference to the runner or its emitter. Tool execution
+ * happens inside an LLM dispatch loop; `DispatchContext` is the canonical context the tool
+ * handler receives.
+ */
+export type EmitToolExecutionEndFn = (event: ToolExecutionEndEvent) => void;
+/**
+ * A function that opens a {@link @nhtio/adk!TurnGate} for the current turn.
+ *
+ * @remarks
+ * Injected into {@link @nhtio/adk!TurnContext} as `waitFor`. The runner closure supplies `turnId` and
+ * `abortSignal` automatically — callers only provide the gate-specific fields.
+ *
+ * @typeParam T - The expected type of the resolution value.
+ */
+export type OpenGateFn = <T>(raw: Omit<RawTurnGate, 'turnId' | 'abortSignal'>) => Promise<T>;
+/**
+ * Functional events emitted by {@link @nhtio/adk!TurnRunner} during a turn.
+ *
+ * @remarks
+ * These events are pipeline-affecting and are registered via `on` / `off` / `once`.
+ *
+ * - `message` — a visible assistant message chunk; may be emitted at any point during the turn.
+ * - `thought` — an internal reasoning/thinking trace chunk; may be emitted at any point during
+ *   the turn. Not shown to end users by default.
+ * - `toolCall` — emitted when the model requests a tool call and again when the result is
+ *   available. Check {@link TurnToolCallContent.isComplete} to distinguish the two emissions.
+ */
+export type TurnEvents = EventMap<{
+    message: [
+        TurnStreamableContent
+    ];
+    thought: [
+        TurnStreamableContent
+    ];
+    toolCall: [
+        TurnToolCallContent
+    ];
+}>;
+/**
+ * Observability events emitted by {@link @nhtio/adk!TurnRunner} for instrumentation.
+ *
+ * @remarks
+ * These events are for monitoring and instrumentation only and are registered via
+ * `observe` / `unobserve` / `observeOnce`. They do not affect pipeline execution.
+ *
+ * - `turnStart` — emitted immediately before the input pipeline runs.
+ * - `turnEnd` — emitted after the pipeline completes (or is aborted/errored).
+ * - `turnGateOpen` — emitted when middleware calls `ctx.waitFor()`, opening a gate.
+ * - `turnGateClosed` — emitted when a gate settles (resolved, rejected, aborted, or timed out).
+ * - `toolExecutionStart` — emitted before a tool handler is called (after arg validation).
+ * - `toolExecutionEnd` — emitted after a tool handler returns or throws.
+ * - `error` — emitted when a non-fatal error occurs inside the input or output pipeline.
+ * - `log` — emitted when the LLM executor (or anything wired through `helpers.log`) writes a
+ *   structured observability record. Carries `dispatchId`, `iteration`, `emittedAt`, `level`,
+ *   `kind`, `message`, and an optional `payload`.
+ */
+export type TurnObservabilityEvents = EventMap<{
+    turnStart: [
+        TurnStartEvent
+    ];
+    turnEnd: [
+        TurnEndEvent
+    ];
+    turnGateOpen: [
+        TurnGate
+    ];
+    turnGateClosed: [
+        TurnGateClosedEvent
+    ];
+    toolExecutionStart: [
+        ToolExecutionStartEvent
+    ];
+    toolExecutionEnd: [
+        ToolExecutionEndEvent
+    ];
+    dispatchStart: [
+        DispatchStartEvent
+    ];
+    dispatchEnd: [
+        DispatchEndEvent
+    ];
+    iterationStart: [
+        IterationStartEvent
+    ];
+    iterationEnd: [
+        IterationEndEvent
+    ];
+    log: [
+        LogEvent
+    ];
+    error: [
+        BaseException
+    ];
+}>;
+/**
+ * Valid event name keys for the {@link @nhtio/adk!TurnRunner} functional bus.
+ *
+ * @typeParam K - Inferred from the key of {@link TurnEvents}.
+ */
+export type TurnEvent<K> = Key<K, TurnEvents>;
+/**
+ * Listener signature for a given {@link @nhtio/adk!TurnRunner} functional event.
+ *
+ * @typeParam K - The event key; inferred from the key of {@link TurnEvents}.
+ */
+export type TurnEventListener<K> = Listener<K, TurnEvents>;
+/**
+ * Valid event name keys for the {@link @nhtio/adk!TurnRunner} observability bus.
+ *
+ * @typeParam K - Inferred from the key of {@link TurnObservabilityEvents}.
+ */
+export type TurnObservabilityEvent<K> = Key<K, TurnObservabilityEvents>;
+/**
+ * Listener signature for a given {@link @nhtio/adk!TurnRunner} observability event.
+ *
+ * @typeParam K - The event key; inferred from the key of {@link TurnObservabilityEvents}.
+ */
+export type TurnObservabilityEventListener<K> = Listener<K, TurnObservabilityEvents>;

package/lib/utils/canonical_json.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Canonical `JSON.stringify` that sorts object keys recursively so that semantically-equal
+ * objects produce identical strings.
+ *
+ * @remarks
+ * Used wherever the ADK derives a stable identity from a structured value — for example,
+ * `Tool.executor` computing the `callId` for `ToolExecutionStart`/`End` events, and the
+ * `reportToolCall` executor helper computing the `checksum` field on `TurnToolCallContent`.
+ * Both code paths hash `canonicalStringify({ tool, args })` so that argument key order does not
+ * affect the resulting identifier.
+ *
+ * Arrays are serialised in their declared order (order is meaningful for an array). Object keys
+ * are sorted with `Array.prototype.sort()`'s default lexicographic comparator.
+ *
+ * @param value - The value to serialise.
+ * @returns A canonical JSON string representation of `value`.
+ */
+export declare function canonicalStringify(value: unknown): string;

package/lib/utils/exceptions.d.ts

@@ -0,0 +1,78 @@
+import { BaseException } from "../classes/base_exception";
+/**
+ * Options accepted by {@link @nhtio/adk!BaseException} (and factory-created exceptions) beyond the
+ * standard `ErrorOptions`.
+ *
+ * @remarks
+ * These mirror the static defaults on {@link @nhtio/adk!BaseException} but allow per-throw overrides so a
+ * single exception class can carry different metadata at different throw sites.
+ */
+export type ExceptionOptions = ErrorOptions & {
+    code?: string;
+    status?: number;
+    fatal?: boolean;
+};
+/**
+ * Constructor signature of an exception class produced by {@link createException}.
+ *
+ * @typeParam T - Tuple of printf-style format argument types. When `T` is an empty tuple the
+ *   constructor takes no positional message arguments; when non-empty the first argument must be
+ *   an array of values matching `T`.
+ */
+export type CreatedException<T extends any[] = [
+]> = typeof BaseException & (T extends [
+] ? {
+    new (options?: ExceptionOptions): BaseException;
+} : {
+    new (args: T, options?: ExceptionOptions): BaseException;
+});
+/**
+ * Factory that produces a named {@link @nhtio/adk!BaseException} subclass with a fixed printf-style message
+ * template, error code, HTTP status, and fatality flag.
+ *
+ * @remarks
+ * Prefer this over hand-writing subclasses for simple, static exception definitions.
+ *
+ * @typeParam T - Tuple of printf format argument types. Pass a non-empty tuple to require
+ *   callers to supply interpolation values at the throw site.
+ *
+ * @param name - The `name` property set on thrown instances (used by {@link isNamedException}).
+ * @param message - Printf-style template string for the error message.
+ * @param code - Machine-readable error code stored on the static and instance `code` property.
+ * @param status - HTTP status code associated with this exception class.
+ * @param fatal - When `true`, signals that the error is unrecoverable.
+ * @returns A constructor for a {@link @nhtio/adk!BaseException} subclass with the given metadata baked in.
+ *
+ * @example
+ * ```ts
+ * export const E_NOT_FOUND = createException<[string]>(
+ *   'E_NOT_FOUND', 'Resource %s not found', 'E_NOT_FOUND', 404, false
+ * )
+ * throw new E_NOT_FOUND(['my-id'])
+ * ```
+ */
+export declare const createException: <T extends any[] = [
+]>(name: string, message: string, code: string, status?: number, fatal?: boolean) => CreatedException<T>;
+/**
+ * Returns `true` if `value` is a {@link @nhtio/adk!BaseException} or satisfies its minimum duck-type shape.
+ *
+ * @remarks
+ * The duck-typing path handles exceptions that cross module or realm boundaries where
+ * `instanceof` would return `false` for structurally identical objects.
+ *
+ * @param value - The value to test.
+ * @returns `true` when `value` conforms to the {@link @nhtio/adk!BaseException} shape.
+ */
+export declare const isException: (value: unknown) => value is BaseException;
+/**
+ * Narrows `value` to a {@link @nhtio/adk!BaseException} whose `name` property matches `name` exactly.
+ *
+ * @remarks
+ * Useful for catching a specific factory-created exception by its string identifier when
+ * `instanceof` checks are not available (e.g. across module boundaries).
+ *
+ * @param value - The value to test.
+ * @param name - The exact string to compare against `value.name`.
+ * @returns `true` when `value` is a {@link @nhtio/adk!BaseException} with the given `name`.
+ */
+export declare const isNamedException: (value: unknown, name: string) => value is BaseException;

package/lib/utils/guards.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Returns `true` if `value` is an instance of the class identified by `type` (and optionally `ctor`).
+ *
+ * @remarks
+ * Performs three checks in order: `instanceof ctor`, `Symbol.hasInstance`, then constructor-name
+ * comparison. The constructor-name fallback handles cross-realm cases where `instanceof` fails.
+ *
+ * @typeParam T - The expected instance type.
+ * @param value - The value to test.
+ * @param type - The constructor name to compare against when `instanceof` is unavailable.
+ * @param ctor - Optional constructor to use for `instanceof` and `Symbol.hasInstance` checks.
+ * @returns `true` when `value` is an instance of the class described by `type`/`ctor`.
+ */
+export declare const isInstanceOf: <T>(value: unknown, type: string, ctor?: new (...args: any[]) => T) => value is T;
+/**
+ * Returns `true` if `value` is an `Error` instance or satisfies the `Error` duck-type shape.
+ *
+ * @remarks
+ * Returns `false` for `undefined` and `null` — the `Error` contract requires an actual instance.
+ *
+ * @param value - The value to test.
+ * @returns `true` when `value` conforms to the `Error` shape.
+ */
+export declare const isError: (value: unknown) => value is Error;
+/**
+ * Type guard to check if a value is a plain object (not null, not array)
+ * @param value - The value to check
+ * @returns True if the value is a plain object, false otherwise
+ */
+export declare const isObject: (value: unknown) => value is {
+    [key: string]: unknown;
+};

package/lib/utils/validation.d.ts

@@ -0,0 +1,77 @@
+import { BaseException } from "../classes/base_exception";
+import { ValidationError } from '@nhtio/validation';
+import type { Schema } from '@nhtio/validation';
+/**
+ * Returns `true` if `value` satisfies `schema` without throwing.
+ *
+ * @remarks
+ * Aborts on the first validation error. Use {@link validateOrThrow} or
+ * {@link asyncValidateOrThrow} when you need the full set of field errors.
+ *
+ * @param schema - The schema to validate against.
+ * @param value - The value to test.
+ * @returns `true` when `value` passes the schema; `false` otherwise.
+ */
+export declare const passesSchema: (schema: Schema, value: unknown) => boolean;
+/**
+ * Returns `true` if `value` is a `ValidationError` or satisfies its minimum duck-type shape.
+ *
+ * @remarks
+ * The duck-typing path handles `ValidationError` objects that cross module or realm boundaries
+ * where `instanceof` would return `false`.
+ *
+ * @param value - The value to test.
+ * @returns `true` when `value` conforms to the `ValidationError` shape.
+ */
+export declare const isValidationError: (value: unknown) => value is ValidationError;
+/**
+ * Thrown when input fails schema validation.
+ *
+ * @remarks
+ * Carries the full `details` array from the underlying `ValidationError` so callers can surface
+ * field-level messages without unwrapping the `cause` manually.
+ */
+export declare class ValidationException extends BaseException {
+    static status: number;
+    static code: string;
+    static fatal: boolean;
+    /** The raw field-level error details from the underlying `ValidationError`. */
+    readonly details?: ValidationError['details'];
+    /**
+     * @param reason - The `ValidationError` thrown by the schema; its `details` are surfaced
+     *   directly on this exception and its messages are joined to form the human-readable message.
+     */
+    constructor(reason: ValidationError);
+}
+/**
+ * Validates `value` against `schema` synchronously and returns the coerced result typed as `T`.
+ *
+ * @remarks
+ * Collects all field errors before throwing. Use {@link asyncValidateOrThrow} for schemas that
+ * include async custom validators.
+ *
+ * @typeParam T - The expected type of `value` after successful validation.
+ * @param schema - The schema to validate against.
+ * @param value - The value to validate.
+ * @param convert - When `true`, the validator coerces values to their target types (e.g. string
+ *   `"1"` → number `1`). Defaults to `false` to prevent silent type coercion.
+ * @returns The validated (and optionally coerced) value typed as `T`.
+ * @throws {@link ValidationException} when `value` does not satisfy `schema`.
+ */
+export declare const validateOrThrow: <T>(schema: Schema, value: unknown, convert?: boolean) => T;
+/**
+ * Validates `value` against `schema` asynchronously and returns the coerced result typed as `T`.
+ *
+ * @remarks
+ * Collects all field errors before throwing. Prefer this over {@link validateOrThrow} when the
+ * schema includes async custom validators.
+ *
+ * @typeParam T - The expected type of the validated and coerced return value.
+ * @param schema - The schema to validate against.
+ * @param value - The value to validate.
+ * @param convert - When `true`, the validator coerces values to their target types (e.g. string
+ *   `"1"` → number `1`). Defaults to `false` to prevent silent type coercion.
+ * @returns The validated (and optionally coerced) value typed as `T`.
+ * @throws {@link ValidationException} when `value` does not satisfy `schema`.
+ */
+export declare const asyncValidateOrThrow: <T>(schema: Schema, value: unknown, convert?: boolean) => Promise<T>;