@nhtio/adk 0.1.0-master-f0aa531d

package/lib/classes/memory.d.ts

@@ -0,0 +1,72 @@
+import { Tokenizable } from "./tokenizable";
+import type { DateTime } from 'luxon';
+/**
+ * Plain input object supplied to {@link Memory} at construction time.
+ *
+ * @remarks
+ * Validated against `rawMemorySchema` before the `Memory` instance is created.
+ * Temporal fields accept any value that Luxon can parse — ISO strings, Unix timestamps,
+ * `Date` objects, or existing `DateTime` instances.
+ */
+export interface RawMemory {
+    /** Stable unique identifier for this memory entry. */
+    id: string;
+    /** The memory content as a plain string or an existing {@link @nhtio/adk!Tokenizable} instance. */
+    content: string | Tokenizable;
+    /** Confidence score in the range `[0, 1]` — how certain the agent is that this memory is accurate. */
+    confidence: number;
+    /** Importance score in the range `[0, 1]` — how much weight this memory should carry during retrieval. */
+    importance: number;
+    /** When this memory was first recorded. */
+    createdAt: string | number | Date | DateTime;
+    /** When this memory was last modified. */
+    updatedAt: string | number | Date | DateTime;
+}
+/**
+ * An immutable, validated memory entry held by the agent.
+ *
+ * @remarks
+ * Constructed from a {@link RawMemory} via `rawMemorySchema`. All temporal fields are
+ * normalised to Luxon `DateTime` instances at construction time. The `content` field is
+ * always a {@link @nhtio/adk!Tokenizable} so callers can estimate token cost without an additional
+ * wrapping step.
+ */
+export declare class Memory {
+    #private;
+    /**
+     * Validator schema that accepts a {@link RawMemory} object.
+     *
+     * @remarks
+     * Reusable fragment for any schema that needs to validate or nest a memory entry — for
+     * example, a collection schema that holds an array of memories.
+     */
+    static schema: import("@nhtio/validation").ObjectSchema<RawMemory>;
+    /**
+     * Returns `true` if `value` is a {@link Memory} 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 Memory} instance.
+     */
+    static isMemory(value: unknown): value is Memory;
+    /** Stable unique identifier for this memory entry. */
+    readonly id: string;
+    /** The memory content as a {@link @nhtio/adk!Tokenizable} for inline token estimation. */
+    readonly content: Tokenizable;
+    /** Confidence score in the range `[0, 1]`. */
+    readonly confidence: number;
+    /** Importance score in the range `[0, 1]`. */
+    readonly importance: number;
+    /** When this memory was first recorded. */
+    readonly createdAt: DateTime;
+    /** When this memory was last modified. */
+    readonly updatedAt: DateTime;
+    /**
+     * @param raw - The raw memory input validated against `rawMemorySchema`.
+     * @throws {@link @nhtio/adk!E_INVALID_INITIAL_MEMORY_VALUE} when `raw` does not satisfy the schema.
+     */
+    constructor(raw: RawMemory);
+}

package/lib/classes/message.d.ts

@@ -0,0 +1,137 @@
+import { Media } from "./media";
+import { Identity } from "./identity";
+import { Tokenizable } from "./tokenizable";
+import type { DateTime } from 'luxon';
+import type { RawIdentity } from "./identity";
+/**
+ * The roles a {@link Message} author can hold.
+ *
+ * @remarks
+ * Restricted to `user` and `assistant` — system instructions, developer directives, and
+ * tool results are handled separately and never appear in the persisted message history.
+ */
+export type MessageRole = 'user' | 'assistant';
+/**
+ * Plain input object supplied to {@link Message} at construction time.
+ *
+ * @remarks
+ * Validated against `rawMessageSchema` before the `Message` instance is created.
+ * Temporal fields accept any value that Luxon can parse — ISO strings, Unix timestamps,
+ * `Date` objects, or existing `DateTime` instances.
+ *
+ * At least one of `content` or `attachments` (non-empty) must be present — a message with
+ * neither throws {@link @nhtio/adk!E_INVALID_INITIAL_MESSAGE_VALUE}.
+ */
+export interface RawMessage {
+    /** Stable unique identifier for this message. */
+    id: string;
+    /** Whether this message is from the human participant or the model. */
+    role: MessageRole;
+    /**
+     * The message content as a plain string or an existing {@link @nhtio/adk!Tokenizable} instance.
+     *
+     * @remarks
+     * Optional — but required when `attachments` is absent or empty. The cross-field rule on
+     * `rawMessageSchema` enforces that at least one of `content` or `attachments` is present.
+     */
+    content?: string | Tokenizable;
+    /**
+     * Media attachments carried by this message — images, audio, video, documents.
+     *
+     * @remarks
+     * Optional and symmetric across roles: both `user` and `assistant` messages may carry
+     * attachments. Each attachment carries its own `trustTier` and `modalityHazard`, which the
+     * renderer uses to wrap the asset in its own trust envelope independent of the message
+     * envelope. How a renderer orders text vs attachments in the on-the-wire content array is
+     * a renderer-policy concern, not a contract of {@link Message}.
+     */
+    attachments?: Media[];
+    /**
+     * The identity of the participant who authored this message.
+     *
+     * @remarks
+     * Optional. When omitted, the `role` value is used as both the system-facing `identifier`
+     * and the model-facing `representation`. 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.
+     */
+    identity?: string | RawIdentity | Identity;
+    /** When this message was created. */
+    createdAt: string | number | Date | DateTime;
+    /** When this message was last modified. */
+    updatedAt: string | number | Date | DateTime;
+}
+/**
+ * An immutable, validated conversation message from a human participant or the model.
+ *
+ * @remarks
+ * Covers only `user` and `assistant` roles — system instructions, developer directives, and
+ * tool results are not represented here. Constructed from a {@link RawMessage} via
+ * `rawMessageSchema`. Temporal fields are normalised to Luxon `DateTime` instances at
+ * construction time. Both `content` and `identity.representation` are {@link @nhtio/adk!Tokenizable} so
+ * token cost can be estimated inline.
+ *
+ * A message may carry `content` (text), `attachments` (media), or both. The cross-field rule
+ * on `rawMessageSchema` enforces that at least one is present. Downstream code that reaches
+ * for `message.content` must handle the attachments-only case where `content` is `undefined`.
+ */
+export declare class Message {
+    #private;
+    /**
+     * Validator schema that accepts a {@link RawMessage} object.
+     *
+     * @remarks
+     * Reusable fragment for any schema that needs to validate or nest a message entry — for
+     * example, a collection schema that holds an array of messages.
+     */
+    static schema: import("@nhtio/validation").ObjectSchema<RawMessage>;
+    /**
+     * Returns `true` if `value` is a {@link Message} 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 Message} instance.
+     */
+    static isMessage(value: unknown): value is Message;
+    /** Stable unique identifier for this message. */
+    readonly id: string;
+    /** Whether this message is from the human participant or the model. */
+    readonly role: MessageRole;
+    /**
+     * The message content as a {@link @nhtio/adk!Tokenizable} for inline token estimation, or `undefined`
+     * for attachments-only messages.
+     *
+     * @remarks
+     * `undefined` when the message was constructed with only `attachments`. Render code that
+     * needs the text portion must guard for the missing case rather than blindly calling
+     * `message.content.toString()`.
+     */
+    readonly content: Tokenizable | undefined;
+    /**
+     * Media attachments carried by this message.
+     *
+     * @remarks
+     * Always defined as a frozen array — empty when the message has no attachments. Both
+     * `user` and `assistant` messages may carry attachments. Each entry carries its own
+     * `trustTier` and `modalityHazard`; the renderer wraps each in its own trust envelope
+     * independent of the message envelope.
+     */
+    readonly attachments: ReadonlyArray<Media>;
+    /** The identity of the participant who authored this message. */
+    readonly identity: Identity;
+    /** When this message was created. */
+    readonly createdAt: DateTime;
+    /** When this message was last modified. */
+    readonly updatedAt: DateTime;
+    /**
+     * @param raw - The raw message input validated against `rawMessageSchema`.
+     * @throws {@link @nhtio/adk!E_INVALID_INITIAL_MESSAGE_VALUE} when `raw` does not satisfy the schema —
+     *   including the cross-field rule that at least one of `content` or `attachments` must be
+     *   present and non-empty.
+     */
+    constructor(raw: RawMessage);
+}

package/lib/classes/registry.d.ts

@@ -0,0 +1,79 @@
+/**
+ * A controlled-mutation key-value store with dot-path access and deep-clone isolation.
+ *
+ * @remarks
+ * The registry enforces a safe read/write contract: callers never hold a live reference into
+ * the internal store. Every value that enters (`set`) or leaves (`get`, `all`) is deep-cloned
+ * via `klona`, so mutations to a retrieved value cannot affect stored state and vice versa.
+ *
+ * Keys are dot-delimited paths (e.g. `"user.profile.name"`), resolved via `dlv` for reads and
+ * `dset` for writes; intermediate objects are created automatically on write.
+ */
+export declare class Registry {
+    #private;
+    /**
+     * @param initial - Optional plain object to seed the registry. Deep-cloned on construction.
+     * @throws {@link @nhtio/adk!E_INVALID_INITIAL_REGISTRY_VALUE} when `initial` is defined but not a plain object.
+     */
+    constructor(initial?: Record<string, unknown>);
+    /**
+     * Returns `true` if `value` is a {@link Registry} instance.
+     *
+     * @remarks
+     * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety.
+     *
+     * @param value - The value to test.
+     * @returns `true` when `value` is a {@link Registry} instance.
+     */
+    static isRegistry(value: unknown): value is Registry;
+    /**
+     * Retrieves the value at `key`, returning `defaultValue` if the path is absent.
+     *
+     * @remarks
+     * The returned value is a deep clone — mutating it will not affect the stored state.
+     *
+     * @typeParam T - Expected type of the value at `key`.
+     * @param key - Dot-delimited path into the store (e.g. `"user.name"`).
+     * @param defaultValue - Fallback returned when the path resolves to `undefined`.
+     * @returns A deep clone of the stored value cast to `T`, or `defaultValue` when the path is absent.
+     */
+    get<T = unknown>(key: string, defaultValue?: T): T;
+    /**
+     * Sets the value at `key`, creating intermediate objects as needed.
+     *
+     * @remarks
+     * The stored value is isolated from the caller — mutating `value` after this call will not
+     * affect what is held in the registry.
+     *
+     * @param key - Dot-delimited path into the store (e.g. `"user.name"`).
+     * @param value - Value to store at the path.
+     */
+    set(key: string, value: unknown): void;
+    /**
+     * Returns `true` if the registry has a value at `key`, `false` otherwise.
+     *
+     * @remarks
+     * A key resolving to `undefined` is treated as absent — same convention as {@link Registry.get}'s
+     * `defaultValue` fallback. No clone is performed; this is a pure existence check.
+     *
+     * @param key - Dot-delimited path into the store (e.g. `"user.name"`).
+     * @returns `true` when the path resolves to a value other than `undefined`.
+     */
+    has(key: string): boolean;
+    /**
+     * Returns all leaf dot-paths present in the registry.
+     *
+     * @remarks
+     * The store is deep-cloned before traversal. Plain objects are walked recursively with path
+     * segments joined by dots; arrays, primitives, `null`, and class instances are treated as leaves.
+     *
+     * @returns A string array of dot-delimited paths to leaf values in the store.
+     */
+    keys(): string[];
+    /**
+     * Returns a deep clone of the entire store contents.
+     *
+     * @returns A plain object snapshot of all stored key-value pairs.
+     */
+    all(): Record<string, unknown>;
+}

package/lib/classes/retrievable.d.ts

@@ -0,0 +1,100 @@
+import { Tokenizable } from "./tokenizable";
+import type { DateTime } from 'luxon';
+/**
+ * Trust-tier discriminator declared by the retrieval middleware at construction time. Drives
+ * which envelope the LLM battery wraps the record in.
+ *
+ * @remarks
+ * Vocabulary deliberately mirrors the published security-research taxonomy ("first-party /
+ * third-party" per *Hidden-in-Plain-Text* WWW '26 and *When AI Meets the Web* IEEE S&P 2026)
+ * and explicitly avoids the words "user" or "system" so the names cannot leak into the model's
+ * OpenAI-Model-Spec role-tier authority resolution.
+ *
+ * - `'first-party'` — deployer-vetted corpora (signed internal docs, policy KBs, curated
+ *   reference material). Rendered as a `<retrieved_corpus>` parent with per-record nonce-keyed
+ *   `<retrieved>` children. The label "first-party" never appears in the envelope itself.
+ * - `'third-party-public'` — open-web scrapes, search results, public APIs. Rendered through
+ *   the untrusted-content envelope with `kind: 'retrieved-third-party-public'`.
+ * - `'third-party-private'` — user uploads, pasted attachments, partner APIs. Rendered through
+ *   the untrusted-content envelope with `kind: 'retrieved-third-party-private'`.
+ */
+export type RetrievableTrustTier = 'first-party' | 'third-party-public' | 'third-party-private';
+/**
+ * Plain input object supplied to {@link Retrievable} at construction time.
+ *
+ * @remarks
+ * Validated against `rawRetrievableSchema` before the `Retrievable` instance is created.
+ * Temporal fields accept any value that Luxon can parse — ISO strings, Unix timestamps,
+ * `Date` objects, or existing `DateTime` instances.
+ */
+export interface RawRetrievable {
+    /**
+     * Stable unique identifier for this retrieved record. Used as the closing-tag nonce in the
+     * rendered envelope, so it must be unguessable from the payload.
+     */
+    id: string;
+    /** The retrieved content as a plain string or an existing {@link @nhtio/adk!Tokenizable} instance. */
+    content: string | Tokenizable;
+    /**
+     * Trust tier declared by the retrieval middleware at construction time. Required — there is
+     * NO default. The decision must be conscious. See {@link RetrievableTrustTier}.
+     */
+    trustTier: RetrievableTrustTier;
+    /** Optional provenance string: URL, document path, knowledge-base id, etc. */
+    source?: string;
+    /** Optional semantic label: 'policy' | 'reference' | 'web-page' | 'pdf' | etc. */
+    kind?: string;
+    /** Optional relevance / similarity score in `[0, 1]` from the retrieval middleware. */
+    score?: number;
+    /** When the source record was created (publication date, upload date, etc.). */
+    createdAt: string | number | Date | DateTime;
+    /** When the source record was last modified. */
+    updatedAt: string | number | Date | DateTime;
+}
+/**
+ * An immutable, validated retrieved record (RAG content) held by the agent.
+ *
+ * @remarks
+ * Peer of {@link @nhtio/adk!Memory} / `Message` / `Thought` / `ToolCall`. Carries an explicit `trustTier`
+ * that LLM batteries branch on to choose the rendering envelope. The retrieval middleware that
+ * produced the record is the only party that knows its provenance — batteries MUST NOT
+ * auto-classify or infer the tier from `source`.
+ */
+export declare class Retrievable {
+    #private;
+    /**
+     * Validator schema that accepts a {@link RawRetrievable} object.
+     *
+     * @remarks
+     * Reusable fragment for any schema that needs to validate or nest a retrievable record.
+     */
+    static schema: import("@nhtio/validation").ObjectSchema<RawRetrievable>;
+    /**
+     * Returns `true` if `value` is a {@link Retrievable} instance.
+     *
+     * @remarks
+     * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety.
+     */
+    static isRetrievable(value: unknown): value is Retrievable;
+    /** Stable unique identifier for this retrieved record. */
+    readonly id: string;
+    /** The retrieved content as a {@link @nhtio/adk!Tokenizable} for inline token estimation. */
+    readonly content: Tokenizable;
+    /** Trust tier declared by the retrieval middleware. */
+    readonly trustTier: RetrievableTrustTier;
+    /** Optional provenance string. */
+    readonly source: string | undefined;
+    /** Optional semantic label. */
+    readonly kind: string | undefined;
+    /** Optional relevance / similarity score in `[0, 1]`. */
+    readonly score: number | undefined;
+    /** When the source record was created. */
+    readonly createdAt: DateTime;
+    /** When the source record was last modified. */
+    readonly updatedAt: DateTime;
+    /**
+     * @param raw - The raw retrievable input validated against `rawRetrievableSchema`.
+     * @throws {@link @nhtio/adk/exceptions!E_INVALID_INITIAL_RETRIEVABLE_VALUE} when `raw` does not satisfy the schema.
+     */
+    constructor(raw: RawRetrievable);
+}