@nhtio/adk 0.1.0-master-f0aa531d

package/lib/types/dispatch_context.d.ts

@@ -0,0 +1,233 @@
+import type { HookHandler } from '@nhtio/hooks';
+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 { Tokenizable } from "../classes/tokenizable";
+import type { TurnStreamableContent, TurnToolCallContent, ToolExecutionStartEvent, ToolExecutionEndEvent } from "./turn_runner";
+/**
+ * Hook event map for {@link @nhtio/adk!DispatchContext}.
+ *
+ * @remarks
+ * Each key maps to a tuple of `[HookArgs, CleanupArgs]`. These events mirror the functional and
+ * observability events on {@link @nhtio/adk!TurnRunner} but are surfaced through `@nhtio/hooks` rather than
+ * `TypedEventEmitter`, which allows the entire execution context to be garbage-collected once
+ * execution completes — no lingering listener references.
+ *
+ * Mutation hooks (`stored*` / `mutated*` / `deleted*`) fire on every mutation in both standalone
+ * and derived paths. The `DispatchRunner` subscribes to these hooks to queue deltas for
+ * later bubbling to a parent `TurnContext`; users may subscribe for observability or testing.
+ */
+export type DispatchContextHooks = {
+    /** Fired when a streaming message chunk is emitted during execution. */
+    message: [
+        [
+            TurnStreamableContent
+        ],
+        [
+        ]
+    ];
+    /** Fired when a reasoning trace chunk is emitted during execution. */
+    thought: [
+        [
+            TurnStreamableContent
+        ],
+        [
+        ]
+    ];
+    /** Fired when a tool call is emitted (on request and again on settlement). */
+    toolCall: [
+        [
+            TurnToolCallContent
+        ],
+        [
+        ]
+    ];
+    /** Fired immediately before a tool handler is called (after arg validation). */
+    toolExecutionStart: [
+        [
+            ToolExecutionStartEvent
+        ],
+        [
+        ]
+    ];
+    /** Fired after a tool handler returns or throws. */
+    toolExecutionEnd: [
+        [
+            ToolExecutionEndEvent
+        ],
+        [
+        ]
+    ];
+    /** Fired after a standing instruction is stored locally and persisted. */
+    storedStandingInstruction: [
+        [
+            Tokenizable
+        ],
+        [
+        ]
+    ];
+    /** Fired after a standing instruction is mutated locally and persisted. */
+    mutatedStandingInstruction: [
+        [
+            Tokenizable
+        ],
+        [
+        ]
+    ];
+    /** Fired after a standing instruction is removed locally and from persistence. */
+    deletedStandingInstruction: [
+        [
+            Tokenizable
+        ],
+        [
+        ]
+    ];
+    /** Fired after a memory is stored locally and persisted. */
+    storedMemory: [
+        [
+            Memory
+        ],
+        [
+        ]
+    ];
+    /** Fired after a memory is mutated locally and persisted. */
+    mutatedMemory: [
+        [
+            Memory
+        ],
+        [
+        ]
+    ];
+    /** Fired after a memory is removed locally and from persistence. Payload is the deleted id. */
+    deletedMemory: [
+        [
+            string
+        ],
+        [
+        ]
+    ];
+    /** Fired after a retrievable record is stored locally and persisted. */
+    storedRetrievable: [
+        [
+            Retrievable
+        ],
+        [
+        ]
+    ];
+    /** Fired after a retrievable record is mutated locally and persisted. */
+    mutatedRetrievable: [
+        [
+            Retrievable
+        ],
+        [
+        ]
+    ];
+    /** Fired after a retrievable record is removed locally and from persistence. Payload is the deleted id. */
+    deletedRetrievable: [
+        [
+            string
+        ],
+        [
+        ]
+    ];
+    /** Fired after a message is stored locally and persisted. */
+    storedMessage: [
+        [
+            Message
+        ],
+        [
+        ]
+    ];
+    /** Fired after a message is mutated locally and persisted. */
+    mutatedMessage: [
+        [
+            Message
+        ],
+        [
+        ]
+    ];
+    /** Fired after a message is removed locally and from persistence. Payload is the deleted id. */
+    deletedMessage: [
+        [
+            string
+        ],
+        [
+        ]
+    ];
+    /** Fired after a thought is stored locally and persisted. */
+    storedThought: [
+        [
+            Thought
+        ],
+        [
+        ]
+    ];
+    /** Fired after a thought is mutated locally and persisted. */
+    mutatedThought: [
+        [
+            Thought
+        ],
+        [
+        ]
+    ];
+    /** Fired after a thought is removed locally and from persistence. Payload is the deleted id. */
+    deletedThought: [
+        [
+            string
+        ],
+        [
+        ]
+    ];
+    /**
+     * Fired after a tool call is stored locally and persisted.
+     *
+     * @remarks
+     * `ToolCall`s with `fromArtifactTool === true` originated from an
+     * {@link @nhtio/adk!ArtifactTool} invocation and carry a
+     * {@link @nhtio/adk!Tokenizable} in `results` (NOT a
+     * {@link @nhtio/adk!SpooledArtifact}). Subsequent
+     * `SpooledArtifact.forgeTools(ctx)` calls filter these out of the `callId` enum to prevent
+     * the artifact-grep-on-an-artifact-grep recursion.
+     */
+    storedToolCall: [
+        [
+            ToolCall
+        ],
+        [
+        ]
+    ];
+    /**
+     * Fired after a tool call is mutated locally and persisted.
+     *
+     * @remarks
+     * See {@link DispatchContextHooks.storedToolCall} for the `fromArtifactTool` /
+     * `Tokenizable`-shaped `results` invariant.
+     */
+    mutatedToolCall: [
+        [
+            ToolCall
+        ],
+        [
+        ]
+    ];
+    /** Fired after a tool call is removed locally and from persistence. Payload is the deleted id. */
+    deletedToolCall: [
+        [
+            string
+        ],
+        [
+        ]
+    ];
+};
+/**
+ * Optional hook registrations supplied to {@link @nhtio/adk!DispatchContext} at construction time.
+ *
+ * @remarks
+ * Each key may be a single handler or an array of handlers. Handlers are registered in order and
+ * fired synchronously (fire-and-forget) on each corresponding emit call.
+ */
+export type DispatchContextHookRegistrations = {
+    [E in keyof DispatchContextHooks]?: HookHandler<DispatchContextHooks[E][0], DispatchContextHooks[E][1]> | HookHandler<DispatchContextHooks[E][0], DispatchContextHooks[E][1]>[];
+};

package/lib/types/dispatch_runner.d.ts

@@ -0,0 +1,387 @@
+import type { DateTime } from 'luxon';
+import type { NextFn } from '@nhtio/middleware';
+import type { HookHandler } from '@nhtio/hooks';
+import type { BaseException } from "../classes/base_exception";
+import type { DispatchContext } from "../contracts/dispatch_context";
+import type { TurnStreamableContent, TurnToolCallContent, ToolExecutionStartEvent, ToolExecutionEndEvent } from "./turn_runner";
+/**
+ * Middleware function signature for the input and output pipelines in {@link @nhtio/adk!DispatchRunner}.
+ *
+ * @remarks
+ * Receives the active {@link @nhtio/adk!DispatchContext} and a `next` callback to advance the pipeline.
+ * Middleware can inspect `ctx.isSignalled` to bail early when an earlier middleware or the
+ * executor has called `ctx.ack()` / `ctx.nack()`, and `ctx.aborted` for external cancellation.
+ * Use `ctx.iteration` and `ctx.toolCallCount(checksum)` to implement iteration bounds and
+ * checksum-repeat bounds in your own middleware — the runner itself does not impose either.
+ */
+export type DispatchPipelineMiddlewareFn = (ctx: DispatchContext, next: NextFn) => void | Promise<void>;
+/**
+ * Per-dispatch helpers passed to {@link DispatchExecutorFn} alongside the active
+ * {@link @nhtio/adk!DispatchContext}.
+ *
+ * @remarks
+ * `DispatchRunner` constructs a fresh helpers instance for every dispatch and threads it
+ * through every iteration of that dispatch. Per-id stream state is scoped to the dispatch —
+ * helpers are garbage-collected with the runner, so cross-dispatch state cannot leak.
+ *
+ * Helpers are **emit-only**: they call `ctx.emitMessage` / `ctx.emitThought` /
+ * `ctx.emitToolCall` to surface streaming content. They do not persist `Message` / `Thought` /
+ * `ToolCall` records, because building those records requires implementation-specific fields
+ * (`role`, `identity`, `SpooledArtifact` for results) that the wire payload doesn't carry. The
+ * executor calls `ctx.storeMessage(...)` / `ctx.storeThought(...)` / `ctx.storeToolCall(...)`
+ * itself when it has the full record assembled.
+ *
+ * The value the helpers add is per-id accumulation state. Without them, every executor
+ * reimplements a per-id `Map<id, { full, createdAt, ... }>` to track streaming chunks across
+ * SDK callbacks.
+ */
+export interface DispatchExecutorHelpers {
+    /**
+     * Append a delta to the message stream for `id` and emit a {@link @nhtio/adk!TurnStreamableContent}.
+     *
+     * @remarks
+     * On the first call for `id`, creates the stream with `createdAt` / `updatedAt` set to now
+     * and `full` equal to `deltaText`. On subsequent calls, appends `deltaText` to the
+     * accumulated `full` and updates `updatedAt`. When `opts.isComplete` is true, sets
+     * `completedAt` and seals the stream — subsequent calls for the same `id` will throw.
+     *
+     * @param id - Stable identifier for this message stream.
+     * @param deltaText - The new chunk to append.
+     * @param opts.isComplete - When true, this is the final chunk for `id`.
+     */
+    reportMessage(id: string, deltaText: string, opts?: {
+        isComplete?: boolean;
+    }): void;
+    /**
+     * Append a delta to the thought stream for `id` and emit a {@link @nhtio/adk!TurnStreamableContent}.
+     *
+     * @remarks
+     * Same accumulation semantics as {@link DispatchExecutorHelpers.reportMessage} but emits via
+     * `ctx.emitThought`. Used for reasoning trace chunks that the executor wants to surface but
+     * not show to the end user.
+     *
+     * @param id - Stable identifier for this thought stream.
+     * @param deltaText - The new chunk to append.
+     * @param opts.isComplete - When true, this is the final chunk for `id`.
+     */
+    reportThought(id: string, deltaText: string, opts?: {
+        isComplete?: boolean;
+    }): void;
+    /**
+     * Update tool call state for `id` and emit a {@link @nhtio/adk!TurnToolCallContent}.
+     *
+     * @remarks
+     * Accepts a partial of the tool call fields; the helper merges into the per-id state and
+     * emits the merged view. Typical usage is two calls: one with `{ tool, args }` to announce
+     * the requested call (helper auto-computes `checksum` via SHA-256 of
+     * `JSON.stringify({tool, args})`), and one with `{ results, isComplete: true, isError? }`
+     * after the tool runs.
+     *
+     * Calls after `isComplete: true` will throw — the per-id state is sealed.
+     *
+     * @param id - Stable identifier for this tool call (correlates request with result).
+     * @param partial - Fields to merge into the tool call state.
+     */
+    reportToolCall(id: string, partial: {
+        tool?: string;
+        args?: unknown;
+        /**
+         * Shape depends on the tool kind backing this call.
+         *
+         * @remarks
+         * For a normal {@link @nhtio/adk!Tool} call, this is typically a
+         * {@link @nhtio/adk!SpooledArtifact} (single or array — a
+         * tool may legitimately spool multiple bounded artifacts in a single call) wrapping
+         * the bytes returned by the handler, or one or more {@link @nhtio/adk!Media}
+         * instances when the handler chose the explicit-modality return path. For an
+         * {@link @nhtio/adk!ArtifactTool} call, this should be the raw
+         * string the handler emitted (`Tokenizable.toString()`-equivalent — already the
+         * model-visible answer). Type stays `unknown` to keep the wire-side payload narrow.
+         */
+        results?: unknown;
+        isError?: boolean;
+        isComplete?: boolean;
+    }): void;
+    /**
+     * Emit a structured log event for the current dispatch.
+     *
+     * @remarks
+     * `trace` / `debug` / `info` / `warn` / `error` mirror the standard syslog severity levels.
+     * Each call routes through the runner's observability bus as a `log` event so middleware,
+     * tests, and consumer observability stacks can subscribe without monkey-patching the
+     * executor. The runner enriches every emission with the active `dispatchId` and 0-based
+     * `iteration` index — call sites only need to supply a `kind` discriminator, a human-readable
+     * message, and an optional structured `payload`.
+     *
+     * The `log` channel is the canonical egress for executor-side diagnostics — retry decisions,
+     * idle / request-timeout fires, HTTP error bodies, SSE chunk anomalies, provider-quirk
+     * warnings, context-window perBucket breakdowns. Use it instead of `console.*`.
+     */
+    log: DispatchExecutorLogChannel;
+}
+/**
+ * Severity of a structured log event emitted by an executor via {@link DispatchExecutorHelpers.log}.
+ *
+ * @remarks
+ * Mirrors the lowercase syslog-style level vocabulary every JS logger converges on
+ * (`pino`, `winston`, `bunyan`, `loglevel`). Consumers filter on the `level` field of the
+ * delivered event — there is no per-level configuration on the channel itself.
+ */
+export type DispatchExecutorLogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Per-call structured payload for {@link DispatchExecutorLogChannel}.
+ *
+ * @remarks
+ * `kind` is a short, stable discriminator the executor authored — observability middleware
+ * matches on it to filter / group / aggregate events without parsing the human-readable
+ * `message`. `payload` is the structured detail block; it is delivered to subscribers verbatim
+ * (the runner never inspects it).
+ */
+export interface DispatchExecutorLogEntry {
+    /** Stable discriminator authored by the executor (e.g. `'retry-attempt'`, `'http-error'`). */
+    kind: string;
+    /** Human-readable message — safe to surface in logs or test failure output. */
+    message: string;
+    /** Optional structured detail block. Delivered to subscribers verbatim. */
+    payload?: Record<string, unknown>;
+}
+/**
+ * Five-level log channel exposed on {@link DispatchExecutorHelpers}.
+ *
+ * @remarks
+ * Each method emits a `log` observability event with the corresponding `level`. Implementations
+ * are non-blocking and side-effect-only — they never throw, never modify the
+ * {@link @nhtio/adk!DispatchContext}, and never participate in ack / nack flow.
+ */
+export interface DispatchExecutorLogChannel {
+    /** Emit a `trace`-level structured log event. */
+    trace(entry: DispatchExecutorLogEntry): void;
+    /** Emit a `debug`-level structured log event. */
+    debug(entry: DispatchExecutorLogEntry): void;
+    /** Emit an `info`-level structured log event. */
+    info(entry: DispatchExecutorLogEntry): void;
+    /** Emit a `warn`-level structured log event. */
+    warn(entry: DispatchExecutorLogEntry): void;
+    /** Emit an `error`-level structured log event. */
+    error(entry: DispatchExecutorLogEntry): void;
+}
+/**
+ * Payload fired on the observability `log` hook for every structured event emitted via
+ * {@link DispatchExecutorHelpers.log}.
+ *
+ * @remarks
+ * Enriched by the runner with the active `dispatchId` and 0-based `iteration` index so
+ * subscribers can correlate events across multiple in-flight dispatches without threading
+ * extra context themselves.
+ */
+export interface LogEvent {
+    /** Stable identifier for the dispatch that produced the event. */
+    dispatchId: string;
+    /** 0-based iteration index within the dispatch. */
+    iteration: number;
+    /** When the event was emitted. */
+    emittedAt: DateTime;
+    /** Severity level the executor selected. */
+    level: DispatchExecutorLogLevel;
+    /** Stable discriminator authored by the executor. */
+    kind: string;
+    /** Human-readable message. */
+    message: string;
+    /** Optional structured detail block. */
+    payload?: Record<string, unknown>;
+}
+/**
+ * The user-supplied callback that performs the actual LLM API call within a dispatch.
+ *
+ * @remarks
+ * Invoked between the input and output middleware pipelines on every iteration. Receives the
+ * active {@link @nhtio/adk!DispatchContext} and an {@link DispatchExecutorHelpers} object that manages
+ * per-id streaming state for the dispatch. The executor's responsibilities:
+ *
+ * 1. Make the actual LLM API / SDK call (the ADK has no opinion on which provider).
+ * 2. Normalise streaming responses into `TurnStreamableContent` / `TurnToolCallContent` shapes
+ *    and report them via the helpers.
+ * 3. Persist the resulting `Message` / `Thought` / `ToolCall` records via `ctx.storeMessage` /
+ *    `ctx.storeThought` / `ctx.storeToolCall` once the implementation-specific fields are
+ *    known.
+ * 4. Decide when the loop is done — typically `ctx.ack()` after a response with no further
+ *    tool calls, or `ctx.nack(err)` on failure. The runner will loop again if neither signal
+ *    nor abort fires.
+ *
+ * Wired into a `TurnRunner` via `TurnRunnerConfig.executorCallback`. Invoked once per
+ * iteration inside `DispatchRunner.dispatch()`, between the input and output middleware
+ * pipelines.
+ */
+export type DispatchExecutorFn = (ctx: DispatchContext, helpers: DispatchExecutorHelpers) => void | Promise<void>;
+/**
+ * Payload fired when a dispatch begins.
+ */
+export interface DispatchStartEvent {
+    /** Stable identifier for this dispatch (UUIDv6). */
+    dispatchId: string;
+    /** When the dispatch began. */
+    startedAt: DateTime;
+}
+/**
+ * Payload fired when a dispatch ends — successfully, by error, or by abort.
+ */
+export interface DispatchEndEvent {
+    /** Stable identifier for this dispatch. */
+    dispatchId: string;
+    /** How the dispatch settled. */
+    status: 'ack' | 'nack' | 'aborted';
+    /** The error stored by `ctx.nack(error)`, or `undefined` for `ack` / `aborted`. */
+    error?: Error;
+    /** Total iterations that ran during this dispatch. */
+    iterations: number;
+    /** When the dispatch began. */
+    startedAt: DateTime;
+    /** When the dispatch ended. */
+    endedAt: DateTime;
+    /** Duration in milliseconds. */
+    durationMs: number;
+}
+/**
+ * Payload fired at the start of each iteration within a dispatch.
+ */
+export interface IterationStartEvent {
+    /** Stable identifier for the parent dispatch. */
+    dispatchId: string;
+    /** 0-based iteration index within the dispatch. */
+    iteration: number;
+    /** When this iteration began. */
+    startedAt: DateTime;
+}
+/**
+ * Payload fired at the end of each iteration within a dispatch.
+ */
+export interface IterationEndEvent {
+    /** Stable identifier for the parent dispatch. */
+    dispatchId: string;
+    /** 0-based iteration index within the dispatch. */
+    iteration: number;
+    /** When this iteration began. */
+    startedAt: DateTime;
+    /** When this iteration ended. */
+    endedAt: DateTime;
+    /** Duration in milliseconds. */
+    durationMs: number;
+}
+/**
+ * Functional hook events on {@link @nhtio/adk!DispatchRunner}.
+ *
+ * @remarks
+ * Pipeline-affecting events forwarded from the {@link @nhtio/adk!DispatchContext}. Register handlers
+ * via the `hooks` field of the dispatch input.
+ */
+export type DispatchRunnerFunctionalHooks = {
+    /** Fired for every streaming message chunk. Forwarded from the context. */
+    message: [
+        [
+            TurnStreamableContent
+        ],
+        [
+        ]
+    ];
+    /** Fired for every reasoning trace chunk. Forwarded from the context. */
+    thought: [
+        [
+            TurnStreamableContent
+        ],
+        [
+        ]
+    ];
+    /** Fired for every tool call (on request and on settlement). Forwarded from the context. */
+    toolCall: [
+        [
+            TurnToolCallContent
+        ],
+        [
+        ]
+    ];
+};
+/**
+ * Observability hook events on {@link @nhtio/adk!DispatchRunner}.
+ *
+ * @remarks
+ * Instrumentation-only events. Register handlers via the `observers` field of the dispatch
+ * input. Removing an observer does not affect dispatch correctness.
+ */
+export type DispatchRunnerObservabilityHooks = {
+    /** Forwarded from the context immediately before a tool handler is called. */
+    toolExecutionStart: [
+        [
+            ToolExecutionStartEvent
+        ],
+        [
+        ]
+    ];
+    /** Forwarded from the context after a tool handler returns or throws. */
+    toolExecutionEnd: [
+        [
+            ToolExecutionEndEvent
+        ],
+        [
+        ]
+    ];
+    /** Fired at the start of each iteration. */
+    iterationStart: [
+        [
+            IterationStartEvent
+        ],
+        [
+        ]
+    ];
+    /** Fired at the end of each iteration. */
+    iterationEnd: [
+        [
+            IterationEndEvent
+        ],
+        [
+        ]
+    ];
+    /** Fired once when the dispatch begins. */
+    dispatchStart: [
+        [
+            DispatchStartEvent
+        ],
+        [
+        ]
+    ];
+    /** Fired once when the dispatch ends (ack / nack / aborted). */
+    dispatchEnd: [
+        [
+            DispatchEndEvent
+        ],
+        [
+        ]
+    ];
+    /** Fired when a non-fatal pipeline or executor error occurs. The exception is also re-thrown. */
+    error: [
+        [
+            BaseException
+        ],
+        [
+        ]
+    ];
+    /** Fired for every structured log event emitted by the executor via {@link DispatchExecutorHelpers.log}. */
+    log: [
+        [
+            LogEvent
+        ],
+        [
+        ]
+    ];
+};
+/**
+ * Optional functional hook registrations supplied to {@link @nhtio/adk!DispatchRunner.dispatch}.
+ */
+export type DispatchRunnerFunctionalHookRegistrations = {
+    [E in keyof DispatchRunnerFunctionalHooks]?: HookHandler<DispatchRunnerFunctionalHooks[E][0], DispatchRunnerFunctionalHooks[E][1]> | HookHandler<DispatchRunnerFunctionalHooks[E][0], DispatchRunnerFunctionalHooks[E][1]>[];
+};
+/**
+ * Optional observability hook registrations supplied to {@link @nhtio/adk!DispatchRunner.dispatch}.
+ */
+export type DispatchRunnerObservabilityHookRegistrations = {
+    [E in keyof DispatchRunnerObservabilityHooks]?: HookHandler<DispatchRunnerObservabilityHooks[E][0], DispatchRunnerObservabilityHooks[E][1]> | HookHandler<DispatchRunnerObservabilityHooks[E][0], DispatchRunnerObservabilityHooks[E][1]>[];
+};