@nhtio/adk 0.1.0-master-f0aa531d

package/lib/classes/thought.d.ts

@@ -0,0 +1,142 @@
+import { Identity } from "./identity";
+import { Tokenizable } from "./tokenizable";
+import type { DateTime } from 'luxon';
+import type { RawIdentity } from "./identity";
+/**
+ * Plain input object supplied to {@link Thought} at construction time.
+ *
+ * @remarks
+ * Validated against `rawThoughtSchema` before the `Thought` instance is created.
+ * Temporal fields accept any value that Luxon can parse — ISO strings, Unix timestamps,
+ * `Date` objects, or existing `DateTime` instances.
+ */
+export interface RawThought {
+    /** Stable unique identifier for this thought. */
+    id: string;
+    /** The reasoning content as a plain string or an existing {@link @nhtio/adk!Tokenizable} instance. */
+    content: string | Tokenizable;
+    /**
+     * The identity of the agent who produced this thought.
+     *
+     * @remarks
+     * Required in multi-agent conversations to attribute reasoning traces to a specific agent.
+     * Three accepted forms when provided:
+     * - A plain `string` — used as both `identifier` and `representation`.
+     * - A {@link @nhtio/adk!RawIdentity} object — validated and wrapped into an {@link @nhtio/adk!Identity}.
+     * - An existing {@link @nhtio/adk!Identity} instance — passed through unchanged.
+     *
+     * When omitted, defaults to `'assistant'` (both `identifier` and `representation`).
+     */
+    identity?: string | RawIdentity | Identity;
+    /**
+     * Optional vendor-opaque payload that round-trips back to a matching model wire.
+     *
+     * @remarks
+     * Carries anything the ADK cannot interpret but a specific provider can — for example,
+     * an Anthropic Messages thinking-block `signature`, an OpenAI Responses
+     * `ResponseReasoningItem.encrypted_content` blob, a DeepSeek server-side reasoning handle,
+     * or an MCP-mediated reasoning item.
+     *
+     * When present, an LLM battery MUST treat the thought as **opaque-mode**: do NOT inline
+     * `content` through the plain `<thought>` envelope; serialise `payload` back to the wire in
+     * whichever shape the matching {@link RawThought.replayCompatibility} identifier specifies.
+     * The plain-text `content` is kept alongside for token-accounting and human/observer
+     * inspection — it is not the thing the model sees.
+     *
+     * Cross-field invariant: a present `payload` REQUIRES a present {@link RawThought.replayCompatibility}.
+     * A `payload` without `replayCompatibility` is malformed (the ADK has no way to know
+     * which adapter can consume it) and {@link Thought.schema} rejects with
+     * {@link @nhtio/adk!E_INVALID_INITIAL_THOUGHT_VALUE}.
+     *
+     * @defaultValue `undefined`
+     */
+    payload?: unknown;
+    /**
+     * Optional free-form identifier describing which adapter wire-shape this thought can be
+     * safely replayed into.
+     *
+     * @remarks
+     * Examples (none of these are reserved by the ADK — they are consumer conventions):
+     *   - `'plain-text'` — replayable into every LLM battery
+     *   - `'anthropic-messages-thinking-v1'`
+     *   - `'openai-responses-reasoning-item-v1'`
+     *   - `'deepseek-reasoning-handle-v1'`
+     *
+     * LLM batteries declare via constructor option which tags they can safely replay; matching
+     * opaque thoughts are routed to the wire's typed reasoning channel where it exists, or to a
+     * documented side-channel key on the request body where the wire has none. Non-matching
+     * opaque thoughts are elided from the current dispatch but NOT removed from
+     * `ctx.turnThoughts` — they remain in context so a subsequent dispatch to a different
+     * adapter that DOES declare the matching tag can pick them up.
+     *
+     * Plain-text thoughts (`payload === undefined` AND `replayCompatibility === undefined`, or
+     * explicit `replayCompatibility: 'plain-text'`) are always replayable.
+     *
+     * A `replayCompatibility` without a `payload` is allowed — it documents intent ("this
+     * plain-text thought is only meaningful to a specific fine-tuned variant") without
+     * requiring an opaque blob.
+     *
+     * @defaultValue `undefined`
+     */
+    replayCompatibility?: string;
+    /** When this thought was recorded. */
+    createdAt: string | number | Date | DateTime;
+    /** When this thought was last modified. */
+    updatedAt: string | number | Date | DateTime;
+}
+/**
+ * An immutable, validated internal reasoning trace produced by an agent.
+ *
+ * @remarks
+ * Represents an agent's internal thinking — distinct from {@link @nhtio/adk!Message} (which is part of
+ * the visible conversation) and never shown to end users directly. Carries an `identity` so
+ * reasoning traces can be attributed to a specific agent in multi-agent conversations.
+ * Constructed from a {@link RawThought} via `rawThoughtSchema`. The `content` field is always
+ * a {@link @nhtio/adk!Tokenizable} so token cost can be estimated inline.
+ */
+export declare class Thought {
+    #private;
+    /**
+     * Validator schema that accepts a {@link RawThought} object.
+     *
+     * @remarks
+     * Reusable fragment for any schema that needs to validate or nest a thought entry.
+     */
+    static schema: import("@nhtio/validation").ObjectSchema<RawThought>;
+    /**
+     * Returns `true` if `value` is a {@link Thought} 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 Thought} instance.
+     */
+    static isThought(value: unknown): value is Thought;
+    /** Stable unique identifier for this thought. */
+    readonly id: string;
+    /** The reasoning content as a {@link @nhtio/adk!Tokenizable} for inline token estimation. */
+    readonly content: Tokenizable;
+    /** The identity of the agent who produced this thought. */
+    readonly identity: Identity;
+    /**
+     * Optional vendor-opaque payload that round-trips back to a matching model wire.
+     * See {@link RawThought.payload}.
+     */
+    readonly payload: unknown;
+    /**
+     * Optional wire-shape identifier describing which adapter can safely replay this thought.
+     * See {@link RawThought.replayCompatibility}.
+     */
+    readonly replayCompatibility: string | undefined;
+    /** When this thought was recorded. */
+    readonly createdAt: DateTime;
+    /** When this thought was last modified. */
+    readonly updatedAt: DateTime;
+    /**
+     * @param raw - The raw thought input validated against `rawThoughtSchema`.
+     * @throws {@link @nhtio/adk!E_INVALID_INITIAL_THOUGHT_VALUE} when `raw` does not satisfy the schema.
+     */
+    constructor(raw: RawThought);
+}

package/lib/classes/tokenizable.d.ts

@@ -0,0 +1,124 @@
+/**
+ * The set of supported token encoding identifiers.
+ *
+ * @remarks
+ * Each value maps to a specific estimation backend:
+ * - `gpt2`, `r50k_base`, `p50k_base`, `p50k_edit`, `cl100k_base`, `o200k_base` — exact counts
+ *   via `js-tiktoken` (OpenAI / tiktoken-compatible models).
+ * - `gemini` — exact counts via `@lenml/tokenizer-gemini`, which embeds Gemini's actual
+ *   SentencePiece vocabulary locally with no API call required.
+ * - `llama2` — exact counts via `llama-tokenizer-js` (Llama 1 and 2). Llama 3+ uses a
+ *   different vocabulary and should use the `llama3` identifier once a suitable sync backend
+ *   is available.
+ * - `claude` — heuristic approximation using Anthropic's published ~3.5 chars/token ratio.
+ *   No local tokenizer is available for Claude 3+ models; the Anthropic SDK's
+ *   `messages.countTokens()` API is the only exact path but requires a network call.
+ *
+ * When adding a new encoding, add a case to {@link Tokenizable.estimateTokens}.
+ */
+export declare const TokenEncoding: readonly [
+    "gpt2",
+    "r50k_base",
+    "p50k_base",
+    "p50k_edit",
+    "cl100k_base",
+    "o200k_base",
+    "gemini",
+    "llama2",
+    "claude"
+];
+/**
+ * Union of all recognised token encoding identifier strings.
+ *
+ * @remarks
+ * Derived from {@link TokenEncoding} so the type and the runtime array stay in sync
+ * automatically when new encodings are added.
+ */
+export type TokenEncoding = (typeof TokenEncoding)[number];
+/**
+ * A mutable string with a built-in token counter.
+ *
+ * @remarks
+ * The wrapped string can be read via the standard coercion protocol and updated at any time via
+ * {@link Tokenizable.set}. Token counts are computed lazily on first access per encoding and
+ * cached until the value changes, avoiding redundant encoder invocations when the same content
+ * is measured multiple times across a pipeline.
+ *
+ * Estimation is dispatched by encoding identifier — see {@link TokenEncoding} for the full list
+ * of supported backends and their accuracy characteristics. Unrecognised encodings fall back to
+ * a `ceil(length / 4)` character heuristic.
+ *
+ * The class implements the standard JS value-coercion protocol (`toString`, `valueOf`,
+ * `toJSON`, `toLocaleString`, `Symbol.for('nodejs.util.inspect.custom')`) so instances behave
+ * transparently as strings in most contexts.
+ */
+export declare class Tokenizable {
+    #private;
+    static TokenEncoding: readonly [
+        "gpt2",
+        "r50k_base",
+        "p50k_base",
+        "p50k_edit",
+        "cl100k_base",
+        "o200k_base",
+        "gemini",
+        "llama2",
+        "claude"
+    ];
+    /**
+     * Validator schema that accepts a plain `string` or a {@link Tokenizable} instance.
+     *
+     * @remarks
+     * Reusable fragment for any schema that wants to accept either form — for example,
+     * `systemPrompt` and each item in `standingInstructions` in `turnContextSchema`.
+     */
+    static schema: import("@nhtio/validation").AlternativesSchema<any>;
+    toJSON: () => string;
+    toString: () => string;
+    valueOf: () => string;
+    toLocaleString: () => string;
+    set: (value: string) => void;
+    estimateTokens: (encoding: TokenEncoding) => number;
+    /**
+     * @param value - The initial string value to wrap.
+     */
+    constructor(value: string);
+    /**
+     * Convenience overload for one-off token counting without managing a {@link Tokenizable} instance.
+     *
+     * @remarks
+     * Creates a temporary instance and immediately discards it — no caching benefit. Use the
+     * instance method when you need to count the same value under multiple encodings or when the
+     * value may change over time.
+     *
+     * @param value - The string to count tokens for.
+     * @param encoding - The encoding identifier to use for counting.
+     * @returns The estimated number of tokens.
+     */
+    static estimateTokens(value: string, encoding: TokenEncoding): number;
+    /**
+     * Returns `true` if `value` is a {@link Tokenizable} 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 Tokenizable} instance.
+     */
+    static isTokenizable(value: unknown): value is Tokenizable;
+}
+/**
+ * Returns `true` if `value` is a {@link Tokenizable} instance.
+ *
+ * @remarks
+ * Module-level convenience alias for {@link Tokenizable.isTokenizable}. Prefer this form when
+ * you need a standalone type guard without importing the full class.
+ *
+ * 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 Tokenizable} instance.
+ */
+export declare const isTokenizable: (value: unknown) => value is Tokenizable;

package/lib/classes/tool.d.ts

@@ -0,0 +1,228 @@
+import { Registry } from "./registry";
+import type { Media } from "./media";
+import type { Schema, Description } from '@nhtio/validation';
+import type { DispatchContext } from "../contracts/dispatch_context";
+import type { SpooledArtifact, SpooledArtifactConstructor } from "./spooled_artifact";
+/**
+ * A zero-arg function that returns the {@link @nhtio/adk!SpooledArtifactConstructor} the consumer should
+ * use when wrapping this tool's serialised output into a `ToolCall.results` field.
+ *
+ * @remarks
+ * Why a resolver (and not the constructor itself)? `tool.ts` participates in a module-load
+ * cycle with `spooled_artifact.ts` and `artifact_tool.ts` (`ArtifactTool extends Tool` closes
+ * the loop). Any eager value-level reference to `SpooledArtifact` in `tool.ts` would crash the
+ * cycle with a TDZ error. A resolver lets `tool.ts` validate "is a function" at module-load
+ * time and defer the actual constructor check to validate-time (which always runs after every
+ * module body has executed). Wrap-sites invoke `tool.artifactConstructor?.() ?? SpooledArtifact`
+ * to obtain the final constructor.
+ */
+export type ArtifactConstructorResolver<A extends SpooledArtifact = SpooledArtifact> = () => SpooledArtifactConstructor<A>;
+/**
+ * The execution function for a {@link Tool}.
+ *
+ * @remarks
+ * Receives the raw arguments passed to the executor, the active {@link @nhtio/adk!DispatchContext}, and the
+ * tool's metadata registry.
+ *
+ * Return shapes:
+ * - `string` / `Uint8Array` — opaque serialised output. The ADK does not persist the bytes
+ *   itself; the consumer's executor middleware is responsible for storing them and wrapping
+ *   them via `tool.artifactConstructor?.() ?? SpooledArtifact` when assembling the `ToolCall`
+ *   record.
+ * - {@link @nhtio/adk!Media} / `Media[]` — explicit-modality silo. Bypasses
+ *   {@link Tool.artifactConstructor} — the handler returns the final result shape directly.
+ *   The LLM battery renders each `Media` as a provider-specific content block.
+ */
+export type ToolHandler = (args: unknown, ctx: DispatchContext, meta: Registry) => string | Uint8Array | Media | Media[] | Promise<string | Uint8Array | Media | Media[]>;
+/**
+ * Plain input object supplied to {@link Tool} at construction time.
+ *
+ * @typeParam A - The {@link @nhtio/adk!SpooledArtifact} subtype used to wrap this tool's results when
+ *   the consumer assembles a `ToolCall.results` field. Defaults to {@link @nhtio/adk!SpooledArtifact}
+ *   (plain text). Tools producing JSON output should set this to `SpooledJsonArtifact`; tools
+ *   producing markdown should set it to `SpooledMarkdownArtifact`; consumers can also pass a
+ *   custom subclass.
+ */
+export interface RawTool<A extends SpooledArtifact = SpooledArtifact> {
+    /** Unique identifier used in LLM tool definitions. Recommend lowercase snake_case. */
+    name: string;
+    /** Human-readable description passed to the model to explain what the tool does. */
+    description: string;
+    /** @nhtio/validation schema for the tool's input arguments. Annotate with `.description()`, `.note()`, `.example()` etc. to produce rich LLM tool definitions via `.describe()`. */
+    inputSchema: Schema;
+    /** Execution function. Not exposed as a public property — invoke via `executor()`. */
+    handler: ToolHandler;
+    /**
+     * Zero-arg resolver returning the {@link @nhtio/adk!SpooledArtifactConstructor} the consumer should use
+     * when wrapping this tool's serialised output into a `ToolCall.results` field. Optional —
+     * when omitted, wrap-sites fall back to {@link @nhtio/adk!SpooledArtifact} (plain text).
+     *
+     * @remarks
+     * Recommended call shape: `artifactConstructor: () => SpooledJsonArtifact`. The closure is
+     * the indirection that lets `tool.ts` validate this field without eagerly importing
+     * `SpooledArtifact` (which would crash the `tool.ts ↔ spooled_artifact.ts ↔ artifact_tool.ts`
+     * module-load cycle). At validate time the schema invokes the resolver and verifies its
+     * return value is a `SpooledArtifact`-derived constructor — wrong-shape resolvers throw
+     * {@link @nhtio/adk!E_INVALID_INITIAL_TOOL_VALUE}.
+     *
+     * Wrap-sites (storage batteries, scripted executors) read the constructor via
+     * `tool.artifactConstructor?.() ?? SpooledArtifact`.
+     */
+    artifactConstructor?: ArtifactConstructorResolver<A>;
+    /** Optional arbitrary metadata for this tool (e.g. RBAC scopes, feature flags). Defaults to `{}`. Stored in a {@link @nhtio/adk!Registry} for dot-path access. */
+    meta?: Record<string, unknown>;
+    /**
+     * When `true`, marks this tool as owned by a specific {@link @nhtio/adk!DispatchContext} so that
+     * `ToolRegistry.pruneEphemeral()` will drop it at ctx-completion.
+     *
+     * @remarks
+     * The flag is advisory at the `Tool` level — registries decide what to do with it. The canonical
+     * producer of ephemeral tools is `SpooledArtifact.forgeTools(ctx)`, which sets this to `true`
+     * on every artifact-query tool it emits.
+     *
+     * @defaultValue `false`
+     */
+    ephemeral?: boolean;
+    /**
+     * When `true`, declares that this tool's output should be treated as **trusted developer/user
+     * intent** rather than as untrusted third-party text when surfaced to the model.
+     *
+     * @remarks
+     * LLM batteries read this flag per call when rendering tool-call results. The default
+     * untrusted envelope (e.g. `<untrusted_content>` in the OpenAI Chat Completions battery) is the
+     * secure-by-default treatment for arbitrary tool output. A tool whose output is authored by the
+     * user or operator (Q&A tools surfacing user-authored answers, human-in-the-loop approval
+     * gates, feedback-collection tools, configuration tools returning developer-authored
+     * constants) sets this to `true` so the LLM battery routes the result through its trusted
+     * envelope (`<trusted_content>` in the OpenAI Chat Completions battery).
+     *
+     * Trust is a property of the tool's output, not a property of how a particular battery is
+     * wired — putting the flag here means the trust signal travels with the tool wherever it is
+     * registered, no per-battery string lists, no name-matching to fail-open on typos.
+     *
+     * @defaultValue `false`
+     */
+    trusted?: boolean;
+    /**
+     * Self-declared merge collision policy. Honoured by `ToolRegistry.merge` (NOT by
+     * `ToolRegistry.register`) when this tool collides with another of the same name.
+     *
+     * @remarks
+     * - `'throw'` (default): defer to the merge-level `options.onCollision`. If that is also
+     *   `'throw'`, the merge raises `E_TOOL_ALREADY_REGISTERED`. This matches the default behaviour
+     *   of `ToolRegistry.register`.
+     * - `'replace'`: this tool always wins the collision, regardless of the merge-level option.
+     * - `'keep'`: this tool always loses to any previously-registered tool of the same name.
+     *
+     * Forged artifact-query tools set this to `'replace'` so that merging multiple
+     * `Subclass.forgeTools(ctx)` outputs (whose base-method tools overlap by name) resolves
+     * silently — the descriptors, snapshot, and handler behaviour are interchangeable across
+     * subclasses, so replacement is a behavioural no-op.
+     *
+     * @defaultValue `'throw'`
+     */
+    onCollision?: 'throw' | 'replace' | 'keep';
+}
+/**
+ * A tool definition that serves as the single source of truth for a callable tool: its name,
+ * description, input schema, execution handler, and the {@link @nhtio/adk!SpooledArtifact} subclass that
+ * wraps its serialised output.
+ *
+ * @typeParam A - The {@link @nhtio/adk!SpooledArtifact} subtype this tool's results should be wrapped in.
+ *   Defaults to {@link @nhtio/adk!SpooledArtifact}.
+ *
+ * @remarks
+ * The `inputSchema` is a `@nhtio/validation` schema. It is used at runtime to validate incoming
+ * arguments before the handler is called, and its `.describe()` output provides all the metadata
+ * needed to build a provider-specific LLM tool definition — annotate the schema with
+ * `.description()`, `.note()`, `.example()` etc. once, and that information is available in both
+ * contexts without duplication.
+ *
+ * The handler is private — invoke it only through `executor(ctx)` which validates args, fires
+ * observability events (with a stable `callId` derived from the tool name and arguments), and
+ * wraps handler errors in {@link @nhtio/adk!E_TOOL_DOWNSTREAM_ERROR}. The handler returns serialised bytes
+ * (`string | Uint8Array`); persistence is the consumer's responsibility.
+ *
+ * `artifactConstructor` is the {@link @nhtio/adk!SpooledArtifact} subclass the consumer should use when
+ * wrapping the handler's output into a `ToolCall.results` field. The author declares it once
+ * on the tool instance; the consumer reads it when assembling persisted records.
+ */
+export declare class Tool<A extends SpooledArtifact = SpooledArtifact> {
+    #private;
+    /**
+     * Validator schema that accepts a {@link RawTool} object.
+     *
+     * @remarks
+     * Reusable fragment for any schema that needs to validate or nest a tool entry
+     * (e.g. `TurnRunnerConfig.tools`).
+     */
+    static schema: import("@nhtio/validation").ObjectSchema<RawTool<SpooledArtifact>>;
+    /**
+     * Returns `true` if `value` is a {@link Tool} instance.
+     *
+     * @param value - The value to test.
+     * @returns `true` when `value` is a {@link Tool} instance.
+     */
+    static isTool(value: unknown): value is Tool;
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: Schema;
+    readonly artifactConstructor: ArtifactConstructorResolver<A> | undefined;
+    readonly meta: Registry;
+    readonly ephemeral: boolean;
+    readonly trusted: boolean;
+    readonly onCollision: 'throw' | 'replace' | 'keep';
+    /**
+     * @param raw - The raw tool input validated against `rawToolSchema`.
+     * @throws {@link @nhtio/adk!E_INVALID_INITIAL_TOOL_VALUE} when `raw` does not satisfy the schema.
+     */
+    constructor(raw: RawTool<A>);
+    /**
+     * Validates `args` against the tool's input schema asynchronously.
+     *
+     * @remarks
+     * Async to support schemas with external validators (e.g. database lookups, API calls).
+     * A validation failure throws {@link @nhtio/adk!E_INVALID_TOOL_ARGS} — this indicates a programming error
+     * in the tool call loop, not a downstream failure.
+     *
+     * @param args - The arguments to validate.
+     * @returns The validated (and coerced) arguments.
+     * @throws {@link @nhtio/adk!E_INVALID_TOOL_ARGS} when `args` does not satisfy the input schema.
+     */
+    validate(args: unknown): Promise<unknown>;
+    /**
+     * Returns a bound executor function for this tool against the given turn context.
+     *
+     * @remarks
+     * The executor: (1) computes a stable `callId` as `sha256(canonicalStringify({tool, args}))`
+     * over the **raw, pre-validation args**, (2) validates `args` via {@link Tool.validate},
+     * (3) emits `toolExecutionStart` on the context (with the computed `callId`), (4) calls the
+     * handler, (5) emits `toolExecutionEnd` (with the same `callId`), (6) wraps any handler error
+     * in {@link @nhtio/adk!E_TOOL_DOWNSTREAM_ERROR} before re-throwing.
+     *
+     * The handler returns serialised bytes (`string | Uint8Array`) — persistence is the consumer's
+     * concern. Use {@link Tool.artifactConstructor} when wrapping the bytes into a
+     * `ToolCall.results` field.
+     *
+     * Pattern mirrors `Middleware.runner()` — call once per turn, reuse the returned function.
+     *
+     * @param ctx - The active turn context. Provides emit functions and turn ID.
+     * @returns An async function `(args) => Promise<string | Uint8Array>`.
+     */
+    executor(ctx: DispatchContext): (args: unknown) => Promise<string | Uint8Array | Media | Media[]>;
+    /**
+     * Returns a fully serialisable snapshot of this tool's definition.
+     *
+     * @remarks
+     * The `inputSchema` property is the result of calling `.describe()` on the raw schema — a plain
+     * object carrying all the annotation metadata (descriptions, notes, examples, types) without any
+     * validator functions. Use this to build provider-specific LLM tool definitions.
+     *
+     * @returns `{ name, description, inputSchema }` where `inputSchema` is the schema description.
+     */
+    describe(): {
+        name: string;
+        description: string;
+        inputSchema: Description;
+    };
+}