@nhtio/adk 0.1.0-master-f0aa531d

package/lib/classes/tool_call.d.ts

@@ -0,0 +1,190 @@
+import { Media } from "./media";
+import { Tokenizable } from "./tokenizable";
+import { SpooledArtifact } from "./spooled_artifact";
+import type { DateTime } from 'luxon';
+/**
+ * Union of every shape a {@link ToolCall.results} field may carry.
+ *
+ * @remarks
+ * Three silos with distinct render-time semantics:
+ *
+ * - {@link @nhtio/adk!Tokenizable} — always singular. The {@link @nhtio/adk!ArtifactTool}
+ *   carve-out: a model-visible text answer that explicitly opts out of artifact wrapping to
+ *   break the recursive grep-on-the-grep-result loop.
+ * - {@link @nhtio/adk!SpooledArtifact} or `SpooledArtifact[]` — bounded text output spooled to durable
+ *   storage. A single tool call may legitimately produce multiple artifacts (e.g. one tool
+ *   that returns N PR bodies). LLM adapters render either inline (full body in trust envelope)
+ *   or as a handle reference (forged artifact-query tools).
+ * - {@link @nhtio/adk!Media} or `Media[]` — binary modality output (image, audio, video, document).
+ *   Adapters render as provider-specific content blocks (`image_url`, `input_audio`, `file`,
+ *   etc.). Bytes are lazy — reached only through {@link @nhtio/adk!Media.stream}.
+ */
+export type ToolCallResults = Tokenizable | SpooledArtifact | SpooledArtifact[] | Media | Media[];
+/**
+ * Plain input object supplied to {@link ToolCall} at construction time.
+ *
+ * @remarks
+ * Validated against `rawToolCallSchema` before the `ToolCall` instance is created.
+ * Temporal fields accept any value that Luxon can parse — ISO strings, Unix timestamps,
+ * `Date` objects, or existing `DateTime` instances.
+ */
+export interface RawToolCall {
+    /** Stable unique identifier for this tool call; correlates the request with its result. */
+    id: string;
+    /** Name of the tool the model has requested. */
+    tool: string;
+    /**
+     * Arguments the model supplied for this tool call.
+     *
+     * @remarks
+     * Accepts either a plain object or a JSON-encoded string that deserialises to an object.
+     * Always exposed as a plain object on the constructed {@link ToolCall} instance.
+     */
+    args: string | Record<string, unknown>;
+    /** Integrity checksum over `tool` and `args`; can be used to detect tampering before execution. */
+    checksum: string;
+    /** `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;
+    /**
+     * Result returned by the tool, or error detail when `isError` is `true`.
+     *
+     * @remarks
+     * Three silos with distinct render-time semantics — see {@link ToolCallResults}:
+     *
+     * - For a normal {@link @nhtio/adk!Tool} call whose handler returned `string` or
+     *   `Uint8Array`, this is a {@link @nhtio/adk!SpooledArtifact} (or one of its subclasses) wrapping the
+     *   spooled bytes. Tools that legitimately produce multiple bounded artifacts may return
+     *   a `SpooledArtifact[]`.
+     * - For a `Tool` call whose handler returned a {@link @nhtio/adk!Media} or `Media[]`, this is the same
+     *   media handle(s) — the explicit-modality silo bypasses `SpooledArtifact` wrapping because
+     *   the bytes are binary and rendered as provider-specific content blocks, not text.
+     * - For an {@link @nhtio/adk!ArtifactTool} call (a forged artifact-query tool),
+     *   this is a {@link @nhtio/adk!Tokenizable} holding the raw model-visible answer — `ArtifactTool`
+     *   explicitly opts out of wrapping to break the recursive grep-on-the-grep-result loop.
+     *
+     * The ADK sets {@link RawToolCall.fromArtifactTool} on calls produced by an
+     * `ArtifactTool` so subsequent `forgeTools(ctx)` invocations can filter them out of the
+     * `callId` enum.
+     */
+    results: ToolCallResults;
+    /**
+     * `true` when this tool call originated from an {@link @nhtio/adk!ArtifactTool}
+     * invocation. Defaults to `false`.
+     *
+     * @remarks
+     * Set by the ADK's result-wrapping touch sites when `ArtifactTool.isArtifactTool(tool)`
+     * holds. Read by `SpooledArtifact.forgeTools(ctx)` when building each descriptor's `callId`
+     * enum — calls with this flag set are excluded so the model can't `artifact_grep` on a
+     * previous `artifact_grep` result. Optional in the raw shape (defaults to `false`); always
+     * defined on the constructed {@link ToolCall}.
+     *
+     * @defaultValue `false`
+     */
+    fromArtifactTool?: boolean;
+    /**
+     * When `true` (default), LLM adapters render this tool call's result inline — the full
+     * stringified body is wrapped in the adapter's trust envelope and sent to the model as the
+     * `tool` role content. When `false`, the adapter surfaces the result as a "handle" — a
+     * directions-bearing envelope that tells the model which forged artifact-query tools to call
+     * against this `tc.id` to read the content incrementally.
+     *
+     * @remarks
+     * Policy is the producer's or middleware's call:
+     *   - A normal tool returns its result with `inline: true` by default so its output is shown
+     *     verbatim.
+     *   - Middleware that wants to keep large results out of the model's prompt sets `inline: false`
+     *     (typically via `ctx.mutateToolCall(tc.id, { inline: false })`) before yielding.
+     *   - LLM adapters do not override the flag, do not size-check the result, and do not silently
+     *     switch to the handle pattern.
+     *
+     * For {@link @nhtio/adk!Tokenizable} results, the flag is effectively informational — handles only make
+     * sense for {@link @nhtio/adk!SpooledArtifact} (which is the only result kind the forged artifact-query
+     * tools can read). When `inline: false` is set on a call whose `results` is a `Tokenizable`,
+     * the adapter renders inline anyway and may log a warning.
+     *
+     * @defaultValue `true`
+     */
+    inline?: boolean;
+    /** When this tool call was first created. */
+    createdAt: string | number | Date | DateTime;
+    /** When this tool call was last modified. */
+    updatedAt: string | number | Date | DateTime;
+    /** When the tool call completed. */
+    completedAt: string | number | Date | DateTime;
+}
+/**
+ * An immutable, validated tool call record associated with a turn.
+ *
+ * @remarks
+ * Represents a completed tool invocation from the conversation history — `results`,
+ * `completedAt`, `isComplete`, and `isError` are all present and required.
+ * Temporal fields are normalised to Luxon `DateTime` instances at construction time.
+ */
+export declare class ToolCall {
+    #private;
+    /**
+     * Validator schema that accepts a {@link RawToolCall} object.
+     *
+     * @remarks
+     * Reusable fragment for any schema that needs to validate or nest a tool call entry.
+     */
+    static schema: import("@nhtio/validation").ObjectSchema<RawToolCall>;
+    /**
+     * Returns `true` if `value` is a {@link ToolCall} instance.
+     *
+     * @remarks
+     * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety — `instanceof` would fail for instances
+     * created in a different module copy or VM context.
+     *
+     * @param value - The value to test.
+     * @returns `true` when `value` is a {@link ToolCall} instance.
+     */
+    static isToolCall(value: unknown): value is ToolCall;
+    /** Stable unique identifier for this tool call; correlates the request with its result. */
+    readonly id: string;
+    /** Name of the tool the model has requested. */
+    readonly tool: string;
+    /** Arguments the model supplied for this tool call, always as a plain object. */
+    readonly args: Record<string, unknown>;
+    /** Integrity checksum over `tool` and `args`. */
+    readonly checksum: string;
+    /** `true` once the tool call has finished (successfully or not). */
+    readonly isComplete: boolean;
+    /** `true` when the tool execution produced an error; inspect `results` for detail. */
+    readonly isError: boolean;
+    /**
+     * Result returned by the tool, or error detail when `isError` is `true`.
+     *
+     * @remarks
+     * One of three silos — see {@link ToolCallResults}. {@link @nhtio/adk!SpooledArtifact} or
+     * `SpooledArtifact[]` for normal text-output {@link @nhtio/adk!Tool} calls;
+     * {@link @nhtio/adk!Media} or `Media[]` for tool calls whose handler returned binary modality output;
+     * {@link @nhtio/adk!Tokenizable} for {@link @nhtio/adk!ArtifactTool} calls
+     * (see {@link ToolCall.fromArtifactTool}).
+     */
+    readonly results: ToolCallResults;
+    /**
+     * `true` when this tool call originated from an {@link @nhtio/adk!ArtifactTool}
+     * invocation. Used by `SpooledArtifact.forgeTools(ctx)` to filter out forged-tool results from
+     * the `callId` enum it builds.
+     */
+    readonly fromArtifactTool: boolean;
+    /**
+     * `true` (default) renders this tool call's result inline in the prompt; `false` instructs LLM
+     * adapters to surface the result as a handle reference. See {@link RawToolCall.inline}.
+     */
+    readonly inline: boolean;
+    /** When this tool call was first created. */
+    readonly createdAt: DateTime;
+    /** When this tool call was last modified. */
+    readonly updatedAt: DateTime;
+    /** When the tool call completed. */
+    readonly completedAt: DateTime;
+    /**
+     * @param raw - The raw tool call input validated against `rawToolCallSchema`.
+     * @throws {@link @nhtio/adk!E_INVALID_INITIAL_TOOL_CALL_VALUE} when `raw` does not satisfy the schema.
+     */
+    constructor(raw: RawToolCall);
+}

package/lib/classes/tool_registry.d.ts

@@ -0,0 +1,159 @@
+import type { Tool } from "./tool";
+import type { DispatchContext } from "../contracts/dispatch_context";
+/**
+ * Options accepted by {@link ToolRegistry.merge}.
+ */
+export interface MergeOptions {
+    /**
+     * What to do when two registries contain a tool with the same name AND neither tool's own
+     * `onCollision` resolves the collision.
+     *
+     * @remarks
+     * - `'throw'` (default): raise {@link @nhtio/adk!E_TOOL_ALREADY_REGISTERED} on the first unresolved
+     *   collision. Mirrors the default behaviour of {@link ToolRegistry.register} and surfaces
+     *   accidental name shadowing immediately.
+     * - `'replace'`: the later registry's tool wins.
+     * - `'keep'`: the earlier registry's tool wins; later occurrences are dropped.
+     *
+     * Per-tool {@link @nhtio/adk!Tool.onCollision} takes precedence: if the incoming tool declares
+     * `'replace'` or `'keep'`, that policy wins regardless of this option. Only when the incoming
+     * tool's policy is `'throw'` (the default) does this fallback apply.
+     *
+     * @defaultValue `'throw'`
+     */
+    onCollision?: 'throw' | 'replace' | 'keep';
+}
+/**
+ * A mutable, turn-scoped collection of {@link @nhtio/adk!Tool} instances.
+ *
+ * @remarks
+ * Each `TurnRunner.run()` call constructs a fresh `ToolRegistry` from the runner's configured
+ * baseline tools, so middleware edits are isolated to the current turn and cannot bleed across
+ * concurrent or subsequent turns.
+ *
+ * `Tool` instances are immutable, so `all()` returns a fresh array without deep-cloning.
+ *
+ * `register()` throws {@link @nhtio/adk!E_TOOL_ALREADY_REGISTERED} if a tool with the same name is already
+ * present — pass `overwrite: true` to replace it explicitly.
+ */
+export declare class ToolRegistry {
+    #private;
+    /**
+     * Returns `true` if `value` is a {@link ToolRegistry} instance.
+     *
+     * @param value - The value to test.
+     * @returns `true` when `value` is a {@link ToolRegistry} instance.
+     */
+    static isToolRegistry(value: unknown): value is ToolRegistry;
+    /**
+     * @param tools - Optional initial tools. Insertion order is preserved. Duplicate names throw
+     *   {@link @nhtio/adk!E_TOOL_ALREADY_REGISTERED} — ensure each tool has a unique name.
+     * @throws {@link @nhtio/adk!E_TOOL_ALREADY_REGISTERED} when two tools in `tools` share a name.
+     */
+    constructor(tools?: Tool[]);
+    /**
+     * Adds a tool to the registry.
+     *
+     * @param tool - The tool to register.
+     * @param overwrite - When `true`, silently replaces an existing tool with the same name.
+     *   Defaults to `false`.
+     * @throws {@link @nhtio/adk!E_TOOL_ALREADY_REGISTERED} when a tool with the same name is already registered
+     *   and `overwrite` is not `true`.
+     */
+    register(tool: Tool, overwrite?: boolean): void;
+    /**
+     * Removes the tool with the given name from the registry.
+     *
+     * @remarks
+     * No-ops if no tool with that name is registered.
+     *
+     * @param name - The name of the tool to remove.
+     */
+    unregister(name: string): void;
+    /**
+     * Returns the tool registered under `name`, or `undefined` if not present.
+     *
+     * @param name - The tool name to look up.
+     */
+    get(name: string): Tool | undefined;
+    /**
+     * Returns `true` if a tool with the given name is registered.
+     *
+     * @param name - The tool name to test.
+     */
+    has(name: string): boolean;
+    /**
+     * Returns a fresh array of all registered tools in insertion order.
+     *
+     * @remarks
+     * Since {@link @nhtio/adk!Tool} instances are immutable, no deep-cloning is needed.
+     */
+    all(): Tool[];
+    /**
+     * Removes every tool whose {@link @nhtio/adk!Tool.ephemeral} flag is `true`.
+     *
+     * @remarks
+     * Synchronous and idempotent — calling it twice in a row is a no-op the second time. The
+     * canonical caller is {@link ToolRegistry.bindContext}, which schedules this method to run
+     * at {@link @nhtio/adk!DispatchContext.ack}. Non-ephemeral tools are left untouched.
+     */
+    pruneEphemeral(): void;
+    /**
+     * Binds this registry to a {@link @nhtio/adk!DispatchContext} so that {@link pruneEphemeral} runs
+     * automatically when the context is acked.
+     *
+     * @remarks
+     * The handler does NOT fire on {@link @nhtio/adk!DispatchContext.nack} — failed executor runs leave
+     * any forged tools in place so the consumer can inspect what was registered when debugging the
+     * failure. Subscriptions are short-lived and die with the context regardless.
+     *
+     * Forgetting this call after merging in `Subclass.forgeTools(ctx)` output means ephemeral tools
+     * accumulate across executor invocations, and subsequent `forgeTools(ctx)` calls in later
+     * iterations will see a stale `callId` enum that excludes new tool calls. The plan-documented
+     * pattern is:
+     *
+     * ```ts
+     * const executor: DispatchExecutorFn = async (ctx) => {
+     *   const forged = SpooledArtifact.forgeTools(ctx)
+     *   const merged = ToolRegistry.merge([main, forged])
+     *   main.bindContext(ctx)
+     *   const result = await llm.invoke({ tools: merged.all(), ... })
+     *   ctx.ack()
+     * }
+     * ```
+     *
+     * @param ctx - The execution context whose `ack` event should trigger pruning.
+     * @returns An unsubscribe function — calling it before `ctx.ack()` prevents pruning. Rarely
+     *   useful outside of tests.
+     *
+     * @see {@link @nhtio/adk!SpooledArtifact.forgeTools}
+     * @see {@link @nhtio/adk!DispatchContext.onAck}
+     */
+    bindContext(ctx: DispatchContext): () => void;
+    /**
+     * Combines multiple {@link ToolRegistry} instances into a fresh registry without mutating any
+     * input.
+     *
+     * @remarks
+     * Iteration is left-to-right across `registries` and then in each registry's insertion order.
+     * Collisions are resolved by consulting the **incoming** tool's {@link @nhtio/adk!Tool.onCollision} first:
+     *
+     * - `'replace'` (per-tool): the incoming tool wins, replacing the existing entry.
+     * - `'keep'` (per-tool): the existing entry wins; the incoming tool is dropped.
+     * - `'throw'` (per-tool, the default): fall back to the merge-level `options.onCollision`.
+     *
+     * The merge-level `options.onCollision` defaults to `'throw'`, which mirrors {@link register}.
+     *
+     * The result is a brand-new registry; no input is mutated and no event subscription is
+     * propagated. Each `Tool`'s `ephemeral` flag carries through unchanged — the flag lives on the
+     * tool, not the registry, so `bindContext(ctx)` on the merged registry will prune the forged
+     * tools as expected.
+     *
+     * @param registries - Registries to merge, in priority order (left-to-right insertion).
+     * @param options - Merge-level collision policy. Defaults to `{ onCollision: 'throw' }`.
+     * @returns A fresh {@link ToolRegistry} containing the resolved union of all inputs.
+     * @throws {@link @nhtio/adk!E_TOOL_ALREADY_REGISTERED} when the resolved collision policy is `'throw'`
+     *   and a collision occurs.
+     */
+    static merge(registries: ToolRegistry[], options?: MergeOptions): ToolRegistry;
+}

package/lib/classes/turn_gate.d.ts

@@ -0,0 +1,109 @@
+import { DateTime } from 'luxon';
+import type { Schema } from '@nhtio/validation';
+/**
+ * Plain input object supplied to {@link TurnGate} at construction time.
+ *
+ * @remarks
+ * `turnId` and `abortSignal` are injected by the runner — callers constructing a gate via
+ * `ctx.waitFor()` never supply them directly.
+ *
+ * `abortSignal` is `AbortSignal` (not `AbortController`) because the gate reacts to turn-level
+ * cancellation but cannot trigger it. The gate owns its own internal `AbortController` for
+ * `gate.abort()`.
+ */
+export interface RawTurnGate {
+    /** Stable unique identifier for this gate. */
+    id: string;
+    /** The ID of the turn that opened this gate. */
+    turnId: string;
+    /** Human-readable label describing why this gate was opened (e.g. `'tool_approval'`). */
+    reason: string;
+    /** Arbitrary data supplied to the gate opener; passed through to `turnGateOpen` listeners. */
+    payload: unknown;
+    /** Optional validator schema for the resolution value. When present, `resolve()` validates before settling. */
+    schema?: Schema;
+    /** Optional timeout in milliseconds. When elapsed the gate self-rejects with {@link @nhtio/adk!E_TURN_GATE_TIMEOUT}. */
+    timeout?: number;
+    /** The turn's abort signal. When fired the gate self-rejects with {@link @nhtio/adk!E_TURN_GATE_ABORTED}. */
+    abortSignal?: AbortSignal;
+    /** When this gate was created. */
+    createdAt: string | number | Date | DateTime;
+}
+/**
+ * A cooperative suspension gate that blocks a turn's middleware pipeline until resolved, rejected,
+ * aborted, or timed out.
+ *
+ * @typeParam T - The expected type of the resolution value.
+ *
+ * @remarks
+ * Created exclusively via `ctx.waitFor()` — middleware never constructs a gate directly.
+ * The gate emits `turnGateOpen` on the runner's observability bus at creation time and
+ * `turnGateClosed` when it settles.
+ *
+ * Resolution is validated against an optional schema before the internal promise is settled.
+ * A validation failure throws {@link @nhtio/adk!E_INVALID_TURN_GATE_RESOLUTION} **synchronously in the
+ * caller's context** — the promise is NOT settled and the gate remains open.
+ */
+export declare class TurnGate<T = unknown> {
+    #private;
+    /**
+     * Validator schema that accepts a {@link RawTurnGate} object.
+     *
+     * @remarks
+     * Reusable fragment for any schema that needs to validate or nest a gate entry.
+     */
+    static schema: import("@nhtio/validation").ObjectSchema<RawTurnGate>;
+    /**
+     * Returns `true` if `value` is a {@link TurnGate} instance.
+     *
+     * @remarks
+     * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety.
+     *
+     * @param value - The value to test.
+     * @returns `true` when `value` is a {@link TurnGate} instance.
+     */
+    static isTurnGate(value: unknown): value is TurnGate;
+    readonly id: string;
+    readonly turnId: string;
+    readonly reason: string;
+    readonly payload: unknown;
+    readonly createdAt: DateTime;
+    readonly isSettled: boolean;
+    /**
+     * @param raw - The raw gate input validated against `rawTurnGateSchema`.
+     * @throws {@link @nhtio/adk!E_INVALID_INITIAL_TURN_GATE_VALUE} when `raw` does not satisfy the schema.
+     */
+    constructor(raw: RawTurnGate);
+    /**
+     * Resolves the gate with `value`, unblocking the awaiting middleware.
+     *
+     * @remarks
+     * If a schema was provided at construction, `value` is validated synchronously before the
+     * promise is settled. A validation failure throws {@link @nhtio/adk!E_INVALID_TURN_GATE_RESOLUTION}
+     * in the caller's context — the promise is NOT settled and the gate remains open.
+     *
+     * No-ops if the gate is already settled.
+     *
+     * @param value - The resolution value. Must satisfy the gate's schema when one was provided.
+     * @throws {@link @nhtio/adk!E_INVALID_TURN_GATE_RESOLUTION} when `value` fails schema validation.
+     */
+    resolve(value: unknown): void;
+    /**
+     * Rejects the gate with `error`, unblocking the awaiting middleware with a rejection.
+     *
+     * @remarks
+     * No-ops if the gate is already settled.
+     *
+     * @param error - The rejection reason.
+     */
+    reject(error: Error): void;
+    /**
+     * Aborts the gate by firing the internal `AbortController`, which rejects the promise with
+     * {@link @nhtio/adk!E_TURN_GATE_ABORTED}.
+     *
+     * @remarks
+     * No-ops if the gate is already settled. Distinct from the turn-level abort signal — this
+     * allows callers to cancel a specific gate without aborting the whole turn.
+     */
+    abort(): void;
+}