@nhtio/adk 0.1.0-master-e04b0eba → 0.1.0-master-d3e80e7a

package/{thought-DBNsR6l8.js.map → thought-BD6AkkOr.js.map}

@@ -1 +1 @@
-{"version":3,"file":"thought-DBNsR6l8.js","names":["#identifier","#representation","#id","#content","#confidence","#importance","#createdAt","#updatedAt","#id","#role","#content","#attachments","#identity","#createdAt","#updatedAt","#id","#content","#identity","#payload","#replayCompatibility","#createdAt","#updatedAt"],"sources":["../src/lib/classes/identity.ts","../src/lib/classes/memory.ts","../src/lib/classes/message.ts","../src/lib/classes/thought.ts"],"sourcesContent":["import { Tokenizable } from './tokenizable'\nimport { validator } from '@nhtio/validation'\nimport { validateOrThrow } from '../utils/validation'\nimport { isInstanceOf, isError } from '../utils/guards'\nimport { E_INVALID_INITIAL_IDENTITY_VALUE } from '../exceptions/runtime'\n\n/**\n * Plain input object supplied to {@link Identity} at construction time.\n *\n * @remarks\n * Validated against `rawIdentitySchema` before the `Identity` instance is created.\n */\nexport interface RawIdentity {\n  /**\n   * The system-facing identifier for this participant.\n   *\n   * @remarks\n   * Used internally to correlate messages to a specific participant — e.g. a database ID or\n   * a username. Never sent to the model directly; use `representation` for that.\n   */\n  identifier: string | number\n  /**\n   * How this participant should be presented to the model.\n   *\n   * @remarks\n   * Accepts a plain string or an existing {@link @nhtio/adk!Tokenizable} instance. This is what the model\n   * sees when it needs to distinguish between participants of the same role.\n   */\n  representation: string | Tokenizable\n}\n\n/**\n * A fully-resolved {@link RawIdentity} where `representation` has been normalised to a\n * {@link @nhtio/adk!Tokenizable} instance.\n *\n * @remarks\n * Used internally by the {@link Identity} constructor to assign private fields with\n * guaranteed types.\n */\ninterface ResolvedIdentity {\n  identifier: string | number\n  representation: Tokenizable\n}\n\n/**\n * Validator schema used to validate a {@link RawIdentity} before constructing an {@link Identity}.\n *\n * @remarks\n * Validates both fields of {@link RawIdentity}:\n * - `identifier` — required string or number.\n * - `representation` — required string or {@link @nhtio/adk!Tokenizable}, via {@link @nhtio/adk!Tokenizable.schema}.\n *\n * Throws {@link @nhtio/adk!E_INVALID_INITIAL_IDENTITY_VALUE} (via the {@link Identity} constructor) when\n * validation fails.\n */\nconst rawIdentitySchema = validator.object<RawIdentity>({\n  identifier: validator.alternatives(validator.string(), validator.number()).required(),\n  representation: Tokenizable.schema.required(),\n})\n\n/**\n * An immutable, validated participant identity attached to a {@link @nhtio/adk!Message}.\n *\n * @remarks\n * Carries two distinct representations of the same participant: `identifier` is the\n * system-facing key (e.g. a database ID) used to correlate messages programmatically;\n * `representation` is what the model sees when it needs to distinguish between participants\n * sharing the same role. The `representation` is always a {@link @nhtio/adk!Tokenizable} so token cost\n * can be estimated inline.\n */\nexport class Identity {\n  /**\n   * Validator schema that accepts a {@link RawIdentity} object.\n   *\n   * @remarks\n   * Reusable fragment for any schema that needs to validate or nest an identity — for example,\n   * as a required field inside a message schema.\n   */\n  public static schema = rawIdentitySchema\n\n  /**\n   * Returns `true` if `value` is an {@link Identity} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety — `instanceof` would fail for instances\n   * created in a different module copy or VM context.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is an {@link Identity} instance.\n   */\n  public static isIdentity(value: unknown): value is Identity {\n    return isInstanceOf(value, 'Identity', Identity)\n  }\n\n  /**\n   * The system-facing identifier for this participant — never sent to the model directly.\n   */\n  declare readonly identifier: string | number\n\n  /**\n   * How this participant is presented to the model, as a {@link @nhtio/adk!Tokenizable} for inline\n   * token estimation.\n   */\n  declare readonly representation: Tokenizable\n\n  #identifier: string | number\n  #representation: Tokenizable\n\n  /**\n   * @param raw - The raw identity input validated against `rawIdentitySchema`.\n   * @throws {@link @nhtio/adk!E_INVALID_INITIAL_IDENTITY_VALUE} when `raw` does not satisfy the schema.\n   */\n  constructor(raw: RawIdentity) {\n    let resolved: ResolvedIdentity\n    try {\n      resolved = validateOrThrow<ResolvedIdentity>(rawIdentitySchema, raw, true)\n    } catch (err) {\n      throw new E_INVALID_INITIAL_IDENTITY_VALUE({ cause: isError(err) ? err : undefined })\n    }\n    this.#identifier = resolved.identifier\n    this.#representation = Tokenizable.isTokenizable(resolved.representation)\n      ? resolved.representation\n      : new Tokenizable(resolved.representation)\n\n    Object.defineProperties(this, {\n      identifier: {\n        get: () => this.#identifier,\n        enumerable: true,\n        configurable: false,\n      },\n      representation: {\n        get: () => this.#representation,\n        enumerable: true,\n        configurable: false,\n      },\n    })\n  }\n}\n","import { Tokenizable } from './tokenizable'\nimport { validator } from '@nhtio/validation'\nimport { validateOrThrow } from '../utils/validation'\nimport { isInstanceOf, isError } from '../utils/guards'\nimport { E_INVALID_INITIAL_MEMORY_VALUE } from '../exceptions/runtime'\nimport type { DateTime } from 'luxon'\n\n/**\n * Plain input object supplied to {@link Memory} at construction time.\n *\n * @remarks\n * Validated against `rawMemorySchema` before the `Memory` instance is created.\n * Temporal fields accept any value that Luxon can parse — ISO strings, Unix timestamps,\n * `Date` objects, or existing `DateTime` instances.\n */\nexport interface RawMemory {\n  /** Stable unique identifier for this memory entry. */\n  id: string\n  /** The memory content as a plain string or an existing {@link @nhtio/adk!Tokenizable} instance. */\n  content: string | Tokenizable\n  /** Confidence score in the range `[0, 1]` — how certain the agent is that this memory is accurate. */\n  confidence: number\n  /** Importance score in the range `[0, 1]` — how much weight this memory should carry during retrieval. */\n  importance: number\n  /** When this memory was first recorded. */\n  createdAt: string | number | Date | DateTime\n  /** When this memory was last modified. */\n  updatedAt: string | number | Date | DateTime\n}\n\n/**\n * A fully-resolved {@link RawMemory} where all fields have been validated and temporal values\n * normalised to Luxon `DateTime` instances.\n *\n * @remarks\n * This is the shape returned by `rawMemorySchema` after validation — used internally by the\n * {@link Memory} constructor to assign private fields with guaranteed types.\n */\ninterface ResolvedMemory {\n  id: string\n  content: Tokenizable\n  confidence: number\n  importance: number\n  createdAt: DateTime\n  updatedAt: DateTime\n}\n\n/**\n * Validator schema used to validate a {@link RawMemory} before constructing a {@link Memory}.\n *\n * @remarks\n * Validates all six fields of {@link RawMemory}:\n * - `id` — required non-empty string.\n * - `content` — required string or {@link @nhtio/adk!Tokenizable}, via {@link @nhtio/adk!Tokenizable.schema}.\n * - `confidence` — required number in `[0, 1]`.\n * - `importance` — required number in `[0, 1]`.\n * - `createdAt` / `updatedAt` — required datetime-parseable values, normalised to `DateTime`.\n *\n * Throws {@link @nhtio/adk!E_INVALID_INITIAL_MEMORY_VALUE} (via the {@link Memory} constructor) when\n * validation fails.\n */\nconst rawMemorySchema = validator.object<RawMemory>({\n  id: validator.string().required(),\n  content: Tokenizable.schema.required(),\n  confidence: validator.number().min(0).max(1).required(),\n  importance: validator.number().min(0).max(1).required(),\n  createdAt: validator.datetime().required(),\n  updatedAt: validator.datetime().required(),\n})\n\n/**\n * An immutable, validated memory entry held by the agent.\n *\n * @remarks\n * Constructed from a {@link RawMemory} via `rawMemorySchema`. All temporal fields are\n * normalised to Luxon `DateTime` instances at construction time. The `content` field is\n * always a {@link @nhtio/adk!Tokenizable} so callers can estimate token cost without an additional\n * wrapping step.\n */\nexport class Memory {\n  /**\n   * Validator schema that accepts a {@link RawMemory} object.\n   *\n   * @remarks\n   * Reusable fragment for any schema that needs to validate or nest a memory entry — for\n   * example, a collection schema that holds an array of memories.\n   */\n  public static schema = rawMemorySchema\n\n  /**\n   * Returns `true` if `value` is a {@link Memory} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety — `instanceof` would fail for instances\n   * created in a different module copy or VM context.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is a {@link Memory} instance.\n   */\n  public static isMemory(value: unknown): value is Memory {\n    return isInstanceOf(value, 'Memory', Memory)\n  }\n  /** Stable unique identifier for this memory entry. */\n  declare readonly id: string\n  /** The memory content as a {@link @nhtio/adk!Tokenizable} for inline token estimation. */\n  declare readonly content: Tokenizable\n  /** Confidence score in the range `[0, 1]`. */\n  declare readonly confidence: number\n  /** Importance score in the range `[0, 1]`. */\n  declare readonly importance: number\n  /** When this memory was first recorded. */\n  declare readonly createdAt: DateTime\n  /** When this memory was last modified. */\n  declare readonly updatedAt: DateTime\n\n  #id: string\n  #content: Tokenizable\n  #confidence: number\n  #importance: number\n  #createdAt: DateTime\n  #updatedAt: DateTime\n\n  /**\n   * @param raw - The raw memory input validated against `rawMemorySchema`.\n   * @throws {@link @nhtio/adk!E_INVALID_INITIAL_MEMORY_VALUE} when `raw` does not satisfy the schema.\n   */\n  constructor(raw: RawMemory) {\n    let resolved: ResolvedMemory\n    try {\n      resolved = validateOrThrow<ResolvedMemory>(rawMemorySchema, raw, true)\n    } catch (err) {\n      throw new E_INVALID_INITIAL_MEMORY_VALUE({ cause: isError(err) ? err : undefined })\n    }\n    this.#id = resolved.id\n    this.#content = Tokenizable.isTokenizable(resolved.content)\n      ? resolved.content\n      : new Tokenizable(resolved.content)\n    this.#confidence = resolved.confidence\n    this.#importance = resolved.importance\n    this.#createdAt = resolved.createdAt\n    this.#updatedAt = resolved.updatedAt\n\n    Object.defineProperties(this, {\n      id: {\n        get: () => this.#id,\n        enumerable: true,\n        configurable: false,\n      },\n      content: {\n        get: () => this.#content,\n        enumerable: true,\n        configurable: false,\n      },\n      confidence: {\n        get: () => this.#confidence,\n        enumerable: true,\n        configurable: false,\n      },\n      importance: {\n        get: () => this.#importance,\n        enumerable: true,\n        configurable: false,\n      },\n      createdAt: {\n        get: () => this.#createdAt,\n        enumerable: true,\n        configurable: false,\n      },\n      updatedAt: {\n        get: () => this.#updatedAt,\n        enumerable: true,\n        configurable: false,\n      },\n    })\n  }\n}\n","import { Media } from './media'\nimport { Identity } from './identity'\nimport { Tokenizable } from './tokenizable'\nimport { validator } from '@nhtio/validation'\nimport { validateOrThrow } from '../utils/validation'\nimport { isInstanceOf, isError } from '../utils/guards'\nimport { E_INVALID_INITIAL_MESSAGE_VALUE } from '../exceptions/runtime'\nimport type { DateTime } from 'luxon'\nimport type { RawIdentity } from './identity'\n\n/**\n * The roles a {@link Message} author can hold.\n *\n * @remarks\n * Restricted to `user` and `assistant` — system instructions, developer directives, and\n * tool results are handled separately and never appear in the persisted message history.\n */\nexport type MessageRole = 'user' | 'assistant'\n\n/**\n * Plain input object supplied to {@link Message} at construction time.\n *\n * @remarks\n * Validated against `rawMessageSchema` before the `Message` instance is created.\n * Temporal fields accept any value that Luxon can parse — ISO strings, Unix timestamps,\n * `Date` objects, or existing `DateTime` instances.\n *\n * At least one of `content` or `attachments` (non-empty) must be present — a message with\n * neither throws {@link @nhtio/adk!E_INVALID_INITIAL_MESSAGE_VALUE}.\n */\nexport interface RawMessage {\n  /** Stable unique identifier for this message. */\n  id: string\n  /** Whether this message is from the human participant or the model. */\n  role: MessageRole\n  /**\n   * The message content as a plain string or an existing {@link @nhtio/adk!Tokenizable} instance.\n   *\n   * @remarks\n   * Optional — but required when `attachments` is absent or empty. The cross-field rule on\n   * `rawMessageSchema` enforces that at least one of `content` or `attachments` is present.\n   */\n  content?: string | Tokenizable\n  /**\n   * Media attachments carried by this message — images, audio, video, documents.\n   *\n   * @remarks\n   * Optional and symmetric across roles: both `user` and `assistant` messages may carry\n   * attachments. Each attachment carries its own `trustTier` and `modalityHazard`, which the\n   * renderer uses to wrap the asset in its own trust envelope independent of the message\n   * envelope. How a renderer orders text vs attachments in the on-the-wire content array is\n   * a renderer-policy concern, not a contract of {@link Message}.\n   */\n  attachments?: Media[]\n  /**\n   * The identity of the participant who authored this message.\n   *\n   * @remarks\n   * Optional. When omitted, the `role` value is used as both the system-facing `identifier`\n   * and the model-facing `representation`. Three accepted forms when provided:\n   * - A plain `string` — used as both `identifier` and `representation`.\n   * - A {@link @nhtio/adk!RawIdentity} object — validated and wrapped into an {@link @nhtio/adk!Identity}.\n   * - An existing {@link @nhtio/adk!Identity} instance — passed through unchanged.\n   */\n  identity?: string | RawIdentity | Identity\n  /** When this message was created. */\n  createdAt: string | number | Date | DateTime\n  /** When this message was last modified. */\n  updatedAt: string | number | Date | DateTime\n}\n\n/**\n * A fully-resolved {@link RawMessage} where temporal fields have been normalised to Luxon\n * `DateTime` instances and `identity` is a validated {@link @nhtio/adk!Identity}.\n *\n * @remarks\n * Used internally by the {@link Message} constructor to assign private fields with\n * guaranteed types.\n */\ninterface ResolvedMessage {\n  id: string\n  role: MessageRole\n  content?: Tokenizable\n  attachments: Media[]\n  identity: string | RawIdentity | Identity\n  createdAt: DateTime\n  updatedAt: DateTime\n}\n\n/**\n * Validator schema used to validate a {@link RawMessage} before constructing a {@link Message}.\n *\n * @remarks\n * Validates all fields of {@link RawMessage}:\n * - `id` — required non-empty string.\n * - `role` — required; must be `'user'` or `'assistant'`.\n * - `content` — optional string or {@link @nhtio/adk!Tokenizable}, via {@link @nhtio/adk!Tokenizable.schema}.\n * - `attachments` — optional array of {@link @nhtio/adk!Media} instances. Defaults to `[]`.\n * - At least one of `content` or `attachments` must be present and non-empty; a message with\n *   neither is invalid.\n * - `identity` — required string, {@link @nhtio/adk!RawIdentity}, or {@link @nhtio/adk!Identity}; a plain string is\n *   mapped to both `identifier` and `representation` automatically.\n * - `createdAt` / `updatedAt` — required datetime-parseable values, normalised to `DateTime`.\n *\n * Throws {@link @nhtio/adk!E_INVALID_INITIAL_MESSAGE_VALUE} (via the {@link Message} constructor) when\n * validation fails.\n */\nconst rawMessageSchema = validator\n  .object<RawMessage>({\n    id: validator.string().required(),\n    role: validator.string().valid('user', 'assistant').required(),\n    content: Tokenizable.schema.optional(),\n    attachments: validator\n      .array()\n      .items(\n        validator.any().custom((value, helpers) => {\n          if (Media.isMedia(value)) return value\n          return helpers.error('any.invalid')\n        })\n      )\n      .default([]),\n    identity: validator\n      .alternatives(validator.string(), Identity.schema)\n      .default(validator.ref('role')),\n    createdAt: validator.datetime().required(),\n    updatedAt: validator.datetime().required(),\n  })\n  .custom((value, helpers) => {\n    const resolved = value as ResolvedMessage\n    const hasContent = resolved.content !== undefined && resolved.content !== null\n    const hasAttachments = Array.isArray(resolved.attachments) && resolved.attachments.length > 0\n    if (!hasContent && !hasAttachments) {\n      return helpers.error('any.invalid')\n    }\n    return resolved\n  })\n\n/**\n * An immutable, validated conversation message from a human participant or the model.\n *\n * @remarks\n * Covers only `user` and `assistant` roles — system instructions, developer directives, and\n * tool results are not represented here. Constructed from a {@link RawMessage} via\n * `rawMessageSchema`. Temporal fields are normalised to Luxon `DateTime` instances at\n * construction time. Both `content` and `identity.representation` are {@link @nhtio/adk!Tokenizable} so\n * token cost can be estimated inline.\n *\n * A message may carry `content` (text), `attachments` (media), or both. The cross-field rule\n * on `rawMessageSchema` enforces that at least one is present. Downstream code that reaches\n * for `message.content` must handle the attachments-only case where `content` is `undefined`.\n */\nexport class Message {\n  /**\n   * Validator schema that accepts a {@link RawMessage} object.\n   *\n   * @remarks\n   * Reusable fragment for any schema that needs to validate or nest a message entry — for\n   * example, a collection schema that holds an array of messages.\n   */\n  public static schema = rawMessageSchema\n\n  /**\n   * Returns `true` if `value` is a {@link Message} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety — `instanceof` would fail for instances\n   * created in a different module copy or VM context.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is a {@link Message} instance.\n   */\n  public static isMessage(value: unknown): value is Message {\n    return isInstanceOf(value, 'Message', Message)\n  }\n\n  /** Stable unique identifier for this message. */\n  declare readonly id: string\n  /** Whether this message is from the human participant or the model. */\n  declare readonly role: MessageRole\n  /**\n   * The message content as a {@link @nhtio/adk!Tokenizable} for inline token estimation, or `undefined`\n   * for attachments-only messages.\n   *\n   * @remarks\n   * `undefined` when the message was constructed with only `attachments`. Render code that\n   * needs the text portion must guard for the missing case rather than blindly calling\n   * `message.content.toString()`.\n   */\n  declare readonly content: Tokenizable | undefined\n  /**\n   * Media attachments carried by this message.\n   *\n   * @remarks\n   * Always defined as a frozen array — empty when the message has no attachments. Both\n   * `user` and `assistant` messages may carry attachments. Each entry carries its own\n   * `trustTier` and `modalityHazard`; the renderer wraps each in its own trust envelope\n   * independent of the message envelope.\n   */\n  declare readonly attachments: ReadonlyArray<Media>\n  /** The identity of the participant who authored this message. */\n  declare readonly identity: Identity\n  /** When this message was created. */\n  declare readonly createdAt: DateTime\n  /** When this message was last modified. */\n  declare readonly updatedAt: DateTime\n\n  #id: string\n  #role: MessageRole\n  #content: Tokenizable | undefined\n  #attachments: ReadonlyArray<Media>\n  #identity: Identity\n  #createdAt: DateTime\n  #updatedAt: DateTime\n\n  /**\n   * @param raw - The raw message input validated against `rawMessageSchema`.\n   * @throws {@link @nhtio/adk!E_INVALID_INITIAL_MESSAGE_VALUE} when `raw` does not satisfy the schema —\n   *   including the cross-field rule that at least one of `content` or `attachments` must be\n   *   present and non-empty.\n   */\n  constructor(raw: RawMessage) {\n    let resolved: ResolvedMessage\n    try {\n      resolved = validateOrThrow<ResolvedMessage>(rawMessageSchema, raw, true)\n    } catch (err) {\n      throw new E_INVALID_INITIAL_MESSAGE_VALUE({ cause: isError(err) ? err : undefined })\n    }\n    this.#id = resolved.id\n    this.#role = resolved.role\n    this.#content =\n      resolved.content === undefined || resolved.content === null\n        ? undefined\n        : Tokenizable.isTokenizable(resolved.content)\n          ? resolved.content\n          : new Tokenizable(resolved.content)\n    this.#attachments = Object.freeze([...(resolved.attachments ?? [])])\n    const rawIdentity = resolved.identity\n    this.#identity = Identity.isIdentity(rawIdentity)\n      ? rawIdentity\n      : typeof rawIdentity === 'string'\n        ? new Identity({ identifier: rawIdentity, representation: rawIdentity })\n        : new Identity(rawIdentity)\n    this.#createdAt = resolved.createdAt\n    this.#updatedAt = resolved.updatedAt\n\n    Object.defineProperties(this, {\n      id: {\n        get: () => this.#id,\n        enumerable: true,\n        configurable: false,\n      },\n      role: {\n        get: () => this.#role,\n        enumerable: true,\n        configurable: false,\n      },\n      content: {\n        get: () => this.#content,\n        enumerable: true,\n        configurable: false,\n      },\n      attachments: {\n        get: () => this.#attachments,\n        enumerable: true,\n        configurable: false,\n      },\n      identity: {\n        get: () => this.#identity,\n        enumerable: true,\n        configurable: false,\n      },\n      createdAt: {\n        get: () => this.#createdAt,\n        enumerable: true,\n        configurable: false,\n      },\n      updatedAt: {\n        get: () => this.#updatedAt,\n        enumerable: true,\n        configurable: false,\n      },\n    })\n  }\n}\n","import { Identity } from './identity'\nimport { Tokenizable } from './tokenizable'\nimport { validator } from '@nhtio/validation'\nimport { validateOrThrow } from '../utils/validation'\nimport { isInstanceOf, isError } from '../utils/guards'\nimport { E_INVALID_INITIAL_THOUGHT_VALUE } from '../exceptions/runtime'\nimport type { DateTime } from 'luxon'\nimport type { RawIdentity } from './identity'\n\n/**\n * Plain input object supplied to {@link Thought} at construction time.\n *\n * @remarks\n * Validated against `rawThoughtSchema` before the `Thought` instance is created.\n * Temporal fields accept any value that Luxon can parse — ISO strings, Unix timestamps,\n * `Date` objects, or existing `DateTime` instances.\n */\nexport interface RawThought {\n  /** Stable unique identifier for this thought. */\n  id: string\n  /** The reasoning content as a plain string or an existing {@link @nhtio/adk!Tokenizable} instance. */\n  content: string | Tokenizable\n  /**\n   * The identity of the agent who produced this thought.\n   *\n   * @remarks\n   * Required in multi-agent conversations to attribute reasoning traces to a specific agent.\n   * Three accepted forms when provided:\n   * - A plain `string` — used as both `identifier` and `representation`.\n   * - A {@link @nhtio/adk!RawIdentity} object — validated and wrapped into an {@link @nhtio/adk!Identity}.\n   * - An existing {@link @nhtio/adk!Identity} instance — passed through unchanged.\n   *\n   * When omitted, defaults to `'assistant'` (both `identifier` and `representation`).\n   */\n  identity?: string | RawIdentity | Identity\n  /**\n   * Optional vendor-opaque payload that round-trips back to a matching model wire.\n   *\n   * @remarks\n   * Carries anything the ADK cannot interpret but a specific provider can — for example,\n   * an Anthropic Messages thinking-block `signature`, an OpenAI Responses\n   * `ResponseReasoningItem.encrypted_content` blob, a DeepSeek server-side reasoning handle,\n   * or an MCP-mediated reasoning item.\n   *\n   * When present, an LLM battery MUST treat the thought as **opaque-mode**: do NOT inline\n   * `content` through the plain `<thought>` envelope; serialise `payload` back to the wire in\n   * whichever shape the matching {@link RawThought.replayCompatibility} identifier specifies.\n   * The plain-text `content` is kept alongside for token-accounting and human/observer\n   * inspection — it is not the thing the model sees.\n   *\n   * Cross-field invariant: a present `payload` REQUIRES a present {@link RawThought.replayCompatibility}.\n   * A `payload` without `replayCompatibility` is malformed (the ADK has no way to know\n   * which adapter can consume it) and {@link Thought.schema} rejects with\n   * {@link @nhtio/adk!E_INVALID_INITIAL_THOUGHT_VALUE}.\n   *\n   * @defaultValue `undefined`\n   */\n  payload?: unknown\n  /**\n   * Optional free-form identifier describing which adapter wire-shape this thought can be\n   * safely replayed into.\n   *\n   * @remarks\n   * Examples (none of these are reserved by the ADK — they are consumer conventions):\n   *   - `'plain-text'` — replayable into every LLM battery\n   *   - `'anthropic-messages-thinking-v1'`\n   *   - `'openai-responses-reasoning-item-v1'`\n   *   - `'deepseek-reasoning-handle-v1'`\n   *\n   * LLM batteries declare via constructor option which tags they can safely replay; matching\n   * opaque thoughts are routed to the wire's typed reasoning channel where it exists, or to a\n   * documented side-channel key on the request body where the wire has none. Non-matching\n   * opaque thoughts are elided from the current dispatch but NOT removed from\n   * `ctx.turnThoughts` — they remain in context so a subsequent dispatch to a different\n   * adapter that DOES declare the matching tag can pick them up.\n   *\n   * Plain-text thoughts (`payload === undefined` AND `replayCompatibility === undefined`, or\n   * explicit `replayCompatibility: 'plain-text'`) are always replayable.\n   *\n   * A `replayCompatibility` without a `payload` is allowed — it documents intent (\"this\n   * plain-text thought is only meaningful to a specific fine-tuned variant\") without\n   * requiring an opaque blob.\n   *\n   * @defaultValue `undefined`\n   */\n  replayCompatibility?: string\n  /** When this thought was recorded. */\n  createdAt: string | number | Date | DateTime\n  /** When this thought was last modified. */\n  updatedAt: string | number | Date | DateTime\n}\n\n/**\n * A fully-resolved {@link RawThought} where temporal fields have been normalised to Luxon\n * `DateTime` instances.\n *\n * @remarks\n * Used internally by the {@link Thought} constructor to assign private fields with\n * guaranteed types.\n */\ninterface ResolvedThought {\n  id: string\n  content: Tokenizable\n  identity: string | RawIdentity | Identity\n  payload?: unknown\n  replayCompatibility?: string\n  createdAt: DateTime\n  updatedAt: DateTime\n}\n\n/**\n * Validator schema used to validate a {@link RawThought} before constructing a {@link Thought}.\n *\n * @remarks\n * Validates all fields of {@link RawThought}:\n * - `id` — required non-empty string.\n * - `content` — required string or {@link @nhtio/adk!Tokenizable}, via {@link @nhtio/adk!Tokenizable.schema}.\n * - `identity` — optional string, {@link @nhtio/adk!RawIdentity}, or {@link @nhtio/adk!Identity}; defaults to\n *   `'assistant'` when omitted.\n * - `createdAt` / `updatedAt` — required datetime-parseable values, normalised to `DateTime`.\n *\n * Throws {@link @nhtio/adk!E_INVALID_INITIAL_THOUGHT_VALUE} (via the {@link Thought} constructor) when\n * validation fails.\n */\nconst rawThoughtSchema = validator\n  .object<RawThought>({\n    id: validator.string().required(),\n    content: Tokenizable.schema.required(),\n    identity: validator.alternatives(validator.string(), Identity.schema).default('assistant'),\n    payload: validator.any().optional(),\n    replayCompatibility: validator.string().min(1).optional(),\n    createdAt: validator.datetime().required(),\n    updatedAt: validator.datetime().required(),\n  })\n  .custom((value, helpers) => {\n    const v = value as RawThought\n    if (\n      v.payload !== undefined &&\n      (v.replayCompatibility === undefined || v.replayCompatibility === null)\n    ) {\n      return helpers.error('any.invalid')\n    }\n    return value\n  })\n\n/**\n * An immutable, validated internal reasoning trace produced by an agent.\n *\n * @remarks\n * Represents an agent's internal thinking — distinct from {@link @nhtio/adk!Message} (which is part of\n * the visible conversation) and never shown to end users directly. Carries an `identity` so\n * reasoning traces can be attributed to a specific agent in multi-agent conversations.\n * Constructed from a {@link RawThought} via `rawThoughtSchema`. The `content` field is always\n * a {@link @nhtio/adk!Tokenizable} so token cost can be estimated inline.\n */\nexport class Thought {\n  /**\n   * Validator schema that accepts a {@link RawThought} object.\n   *\n   * @remarks\n   * Reusable fragment for any schema that needs to validate or nest a thought entry.\n   */\n  public static schema = rawThoughtSchema\n\n  /**\n   * Returns `true` if `value` is a {@link Thought} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety — `instanceof` would fail for instances\n   * created in a different module copy or VM context.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is a {@link Thought} instance.\n   */\n  public static isThought(value: unknown): value is Thought {\n    return isInstanceOf(value, 'Thought', Thought)\n  }\n\n  /** Stable unique identifier for this thought. */\n  declare readonly id: string\n  /** The reasoning content as a {@link @nhtio/adk!Tokenizable} for inline token estimation. */\n  declare readonly content: Tokenizable\n  /** The identity of the agent who produced this thought. */\n  declare readonly identity: Identity\n  /**\n   * Optional vendor-opaque payload that round-trips back to a matching model wire.\n   * See {@link RawThought.payload}.\n   */\n  declare readonly payload: unknown\n  /**\n   * Optional wire-shape identifier describing which adapter can safely replay this thought.\n   * See {@link RawThought.replayCompatibility}.\n   */\n  declare readonly replayCompatibility: string | undefined\n  /** When this thought was recorded. */\n  declare readonly createdAt: DateTime\n  /** When this thought was last modified. */\n  declare readonly updatedAt: DateTime\n\n  #id: string\n  #content: Tokenizable\n  #identity: Identity\n  #payload: unknown\n  #replayCompatibility: string | undefined\n  #createdAt: DateTime\n  #updatedAt: DateTime\n\n  /**\n   * @param raw - The raw thought input validated against `rawThoughtSchema`.\n   * @throws {@link @nhtio/adk!E_INVALID_INITIAL_THOUGHT_VALUE} when `raw` does not satisfy the schema.\n   */\n  constructor(raw: RawThought) {\n    let resolved: ResolvedThought\n    try {\n      resolved = validateOrThrow<ResolvedThought>(rawThoughtSchema, raw, true)\n    } catch (err) {\n      throw new E_INVALID_INITIAL_THOUGHT_VALUE({ cause: isError(err) ? err : undefined })\n    }\n    this.#id = resolved.id\n    this.#content = Tokenizable.isTokenizable(resolved.content)\n      ? resolved.content\n      : new Tokenizable(resolved.content)\n    const rawIdentity = resolved.identity\n    this.#identity = Identity.isIdentity(rawIdentity)\n      ? rawIdentity\n      : typeof rawIdentity === 'string'\n        ? new Identity({ identifier: rawIdentity, representation: rawIdentity })\n        : new Identity(rawIdentity)\n    this.#payload = resolved.payload\n    this.#replayCompatibility = resolved.replayCompatibility\n    this.#createdAt = resolved.createdAt\n    this.#updatedAt = resolved.updatedAt\n\n    Object.defineProperties(this, {\n      id: {\n        get: () => this.#id,\n        enumerable: true,\n        configurable: false,\n      },\n      content: {\n        get: () => this.#content,\n        enumerable: true,\n        configurable: false,\n      },\n      identity: {\n        get: () => this.#identity,\n        enumerable: true,\n        configurable: false,\n      },\n      payload: {\n        get: () => this.#payload,\n        enumerable: true,\n        configurable: false,\n      },\n      replayCompatibility: {\n        get: () => this.#replayCompatibility,\n        enumerable: true,\n        configurable: false,\n      },\n      createdAt: {\n        get: () => this.#createdAt,\n        enumerable: true,\n        configurable: false,\n      },\n      updatedAt: {\n        get: () => this.#updatedAt,\n        enumerable: true,\n        configurable: false,\n      },\n    })\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"thought-BD6AkkOr.js","names":["#identifier","#representation","#id","#content","#confidence","#importance","#createdAt","#updatedAt","#id","#role","#content","#attachments","#identity","#createdAt","#updatedAt","#id","#content","#identity","#payload","#replayCompatibility","#createdAt","#updatedAt"],"sources":["../src/lib/classes/identity.ts","../src/lib/classes/memory.ts","../src/lib/classes/message.ts","../src/lib/classes/thought.ts"],"sourcesContent":["import { Tokenizable } from './tokenizable'\nimport { validator } from '@nhtio/validation'\nimport { validateOrThrow } from '../utils/validation'\nimport { isInstanceOf, isError } from '../utils/guards'\nimport { E_INVALID_INITIAL_IDENTITY_VALUE } from '../exceptions/runtime'\n\n/**\n * Plain input object supplied to {@link Identity} at construction time.\n *\n * @remarks\n * Validated against `rawIdentitySchema` before the `Identity` instance is created.\n */\nexport interface RawIdentity {\n  /**\n   * The system-facing identifier for this participant.\n   *\n   * @remarks\n   * Used internally to correlate messages to a specific participant — e.g. a database ID or\n   * a username. Never sent to the model directly; use `representation` for that.\n   */\n  identifier: string | number\n  /**\n   * How this participant should be presented to the model.\n   *\n   * @remarks\n   * Accepts a plain string or an existing {@link @nhtio/adk!Tokenizable} instance. This is what the model\n   * sees when it needs to distinguish between participants of the same role.\n   */\n  representation: string | Tokenizable\n}\n\n/**\n * A fully-resolved {@link RawIdentity} where `representation` has been normalised to a\n * {@link @nhtio/adk!Tokenizable} instance.\n *\n * @remarks\n * Used internally by the {@link Identity} constructor to assign private fields with\n * guaranteed types.\n */\ninterface ResolvedIdentity {\n  identifier: string | number\n  representation: Tokenizable\n}\n\n/**\n * Validator schema used to validate a {@link RawIdentity} before constructing an {@link Identity}.\n *\n * @remarks\n * Validates both fields of {@link RawIdentity}:\n * - `identifier` — required string or number.\n * - `representation` — required string or {@link @nhtio/adk!Tokenizable}, via {@link @nhtio/adk!Tokenizable.schema}.\n *\n * Throws {@link @nhtio/adk!E_INVALID_INITIAL_IDENTITY_VALUE} (via the {@link Identity} constructor) when\n * validation fails.\n */\nconst rawIdentitySchema = validator.object<RawIdentity>({\n  identifier: validator.alternatives(validator.string(), validator.number()).required(),\n  representation: Tokenizable.schema.required(),\n})\n\n/**\n * An immutable, validated participant identity attached to a {@link @nhtio/adk!Message}.\n *\n * @remarks\n * Carries two distinct representations of the same participant: `identifier` is the\n * system-facing key (e.g. a database ID) used to correlate messages programmatically;\n * `representation` is what the model sees when it needs to distinguish between participants\n * sharing the same role. The `representation` is always a {@link @nhtio/adk!Tokenizable} so token cost\n * can be estimated inline.\n */\nexport class Identity {\n  /**\n   * Validator schema that accepts a {@link RawIdentity} object.\n   *\n   * @remarks\n   * Reusable fragment for any schema that needs to validate or nest an identity — for example,\n   * as a required field inside a message schema.\n   */\n  public static schema = rawIdentitySchema\n\n  /**\n   * Returns `true` if `value` is an {@link Identity} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety — `instanceof` would fail for instances\n   * created in a different module copy or VM context.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is an {@link Identity} instance.\n   */\n  public static isIdentity(value: unknown): value is Identity {\n    return isInstanceOf(value, 'Identity', Identity)\n  }\n\n  /**\n   * The system-facing identifier for this participant — never sent to the model directly.\n   */\n  declare readonly identifier: string | number\n\n  /**\n   * How this participant is presented to the model, as a {@link @nhtio/adk!Tokenizable} for inline\n   * token estimation.\n   */\n  declare readonly representation: Tokenizable\n\n  #identifier: string | number\n  #representation: Tokenizable\n\n  /**\n   * @param raw - The raw identity input validated against `rawIdentitySchema`.\n   * @throws {@link @nhtio/adk!E_INVALID_INITIAL_IDENTITY_VALUE} when `raw` does not satisfy the schema.\n   */\n  constructor(raw: RawIdentity) {\n    let resolved: ResolvedIdentity\n    try {\n      resolved = validateOrThrow<ResolvedIdentity>(rawIdentitySchema, raw, true)\n    } catch (err) {\n      throw new E_INVALID_INITIAL_IDENTITY_VALUE({ cause: isError(err) ? err : undefined })\n    }\n    this.#identifier = resolved.identifier\n    this.#representation = Tokenizable.isTokenizable(resolved.representation)\n      ? resolved.representation\n      : new Tokenizable(resolved.representation)\n\n    Object.defineProperties(this, {\n      identifier: {\n        get: () => this.#identifier,\n        enumerable: true,\n        configurable: false,\n      },\n      representation: {\n        get: () => this.#representation,\n        enumerable: true,\n        configurable: false,\n      },\n    })\n  }\n}\n","import { Tokenizable } from './tokenizable'\nimport { validator } from '@nhtio/validation'\nimport { validateOrThrow } from '../utils/validation'\nimport { isInstanceOf, isError } from '../utils/guards'\nimport { E_INVALID_INITIAL_MEMORY_VALUE } from '../exceptions/runtime'\nimport type { DateTime } from 'luxon'\n\n/**\n * Plain input object supplied to {@link Memory} at construction time.\n *\n * @remarks\n * Validated against `rawMemorySchema` before the `Memory` instance is created.\n * Temporal fields accept any value that Luxon can parse — ISO strings, Unix timestamps,\n * `Date` objects, or existing `DateTime` instances.\n */\nexport interface RawMemory {\n  /** Stable unique identifier for this memory entry. */\n  id: string\n  /** The memory content as a plain string or an existing {@link @nhtio/adk!Tokenizable} instance. */\n  content: string | Tokenizable\n  /** Confidence score in the range `[0, 1]` — how certain the agent is that this memory is accurate. */\n  confidence: number\n  /** Importance score in the range `[0, 1]` — how much weight this memory should carry during retrieval. */\n  importance: number\n  /** When this memory was first recorded. */\n  createdAt: string | number | Date | DateTime\n  /** When this memory was last modified. */\n  updatedAt: string | number | Date | DateTime\n}\n\n/**\n * A fully-resolved {@link RawMemory} where all fields have been validated and temporal values\n * normalised to Luxon `DateTime` instances.\n *\n * @remarks\n * This is the shape returned by `rawMemorySchema` after validation — used internally by the\n * {@link Memory} constructor to assign private fields with guaranteed types.\n */\ninterface ResolvedMemory {\n  id: string\n  content: Tokenizable\n  confidence: number\n  importance: number\n  createdAt: DateTime\n  updatedAt: DateTime\n}\n\n/**\n * Validator schema used to validate a {@link RawMemory} before constructing a {@link Memory}.\n *\n * @remarks\n * Validates all six fields of {@link RawMemory}:\n * - `id` — required non-empty string.\n * - `content` — required string or {@link @nhtio/adk!Tokenizable}, via {@link @nhtio/adk!Tokenizable.schema}.\n * - `confidence` — required number in `[0, 1]`.\n * - `importance` — required number in `[0, 1]`.\n * - `createdAt` / `updatedAt` — required datetime-parseable values, normalised to `DateTime`.\n *\n * Throws {@link @nhtio/adk!E_INVALID_INITIAL_MEMORY_VALUE} (via the {@link Memory} constructor) when\n * validation fails.\n */\nconst rawMemorySchema = validator.object<RawMemory>({\n  id: validator.string().required(),\n  content: Tokenizable.schema.required(),\n  confidence: validator.number().min(0).max(1).required(),\n  importance: validator.number().min(0).max(1).required(),\n  createdAt: validator.datetime().required(),\n  updatedAt: validator.datetime().required(),\n})\n\n/**\n * An immutable, validated memory entry held by the agent.\n *\n * @remarks\n * Constructed from a {@link RawMemory} via `rawMemorySchema`. All temporal fields are\n * normalised to Luxon `DateTime` instances at construction time. The `content` field is\n * always a {@link @nhtio/adk!Tokenizable} so callers can estimate token cost without an additional\n * wrapping step.\n */\nexport class Memory {\n  /**\n   * Validator schema that accepts a {@link RawMemory} object.\n   *\n   * @remarks\n   * Reusable fragment for any schema that needs to validate or nest a memory entry — for\n   * example, a collection schema that holds an array of memories.\n   */\n  public static schema = rawMemorySchema\n\n  /**\n   * Returns `true` if `value` is a {@link Memory} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety — `instanceof` would fail for instances\n   * created in a different module copy or VM context.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is a {@link Memory} instance.\n   */\n  public static isMemory(value: unknown): value is Memory {\n    return isInstanceOf(value, 'Memory', Memory)\n  }\n  /** Stable unique identifier for this memory entry. */\n  declare readonly id: string\n  /** The memory content as a {@link @nhtio/adk!Tokenizable} for inline token estimation. */\n  declare readonly content: Tokenizable\n  /** Confidence score in the range `[0, 1]`. */\n  declare readonly confidence: number\n  /** Importance score in the range `[0, 1]`. */\n  declare readonly importance: number\n  /** When this memory was first recorded. */\n  declare readonly createdAt: DateTime\n  /** When this memory was last modified. */\n  declare readonly updatedAt: DateTime\n\n  #id: string\n  #content: Tokenizable\n  #confidence: number\n  #importance: number\n  #createdAt: DateTime\n  #updatedAt: DateTime\n\n  /**\n   * @param raw - The raw memory input validated against `rawMemorySchema`.\n   * @throws {@link @nhtio/adk!E_INVALID_INITIAL_MEMORY_VALUE} when `raw` does not satisfy the schema.\n   */\n  constructor(raw: RawMemory) {\n    let resolved: ResolvedMemory\n    try {\n      resolved = validateOrThrow<ResolvedMemory>(rawMemorySchema, raw, true)\n    } catch (err) {\n      throw new E_INVALID_INITIAL_MEMORY_VALUE({ cause: isError(err) ? err : undefined })\n    }\n    this.#id = resolved.id\n    this.#content = Tokenizable.isTokenizable(resolved.content)\n      ? resolved.content\n      : new Tokenizable(resolved.content)\n    this.#confidence = resolved.confidence\n    this.#importance = resolved.importance\n    this.#createdAt = resolved.createdAt\n    this.#updatedAt = resolved.updatedAt\n\n    Object.defineProperties(this, {\n      id: {\n        get: () => this.#id,\n        enumerable: true,\n        configurable: false,\n      },\n      content: {\n        get: () => this.#content,\n        enumerable: true,\n        configurable: false,\n      },\n      confidence: {\n        get: () => this.#confidence,\n        enumerable: true,\n        configurable: false,\n      },\n      importance: {\n        get: () => this.#importance,\n        enumerable: true,\n        configurable: false,\n      },\n      createdAt: {\n        get: () => this.#createdAt,\n        enumerable: true,\n        configurable: false,\n      },\n      updatedAt: {\n        get: () => this.#updatedAt,\n        enumerable: true,\n        configurable: false,\n      },\n    })\n  }\n}\n","import { Media } from './media'\nimport { Identity } from './identity'\nimport { Tokenizable } from './tokenizable'\nimport { validator } from '@nhtio/validation'\nimport { validateOrThrow } from '../utils/validation'\nimport { isInstanceOf, isError } from '../utils/guards'\nimport { E_INVALID_INITIAL_MESSAGE_VALUE } from '../exceptions/runtime'\nimport type { DateTime } from 'luxon'\nimport type { RawIdentity } from './identity'\n\n/**\n * The roles a {@link Message} author can hold.\n *\n * @remarks\n * Restricted to `user` and `assistant` — system instructions, developer directives, and\n * tool results are handled separately and never appear in the persisted message history.\n */\nexport type MessageRole = 'user' | 'assistant'\n\n/**\n * Plain input object supplied to {@link Message} at construction time.\n *\n * @remarks\n * Validated against `rawMessageSchema` before the `Message` instance is created.\n * Temporal fields accept any value that Luxon can parse — ISO strings, Unix timestamps,\n * `Date` objects, or existing `DateTime` instances.\n *\n * At least one of `content` or `attachments` (non-empty) must be present — a message with\n * neither throws {@link @nhtio/adk!E_INVALID_INITIAL_MESSAGE_VALUE}.\n */\nexport interface RawMessage {\n  /** Stable unique identifier for this message. */\n  id: string\n  /** Whether this message is from the human participant or the model. */\n  role: MessageRole\n  /**\n   * The message content as a plain string or an existing {@link @nhtio/adk!Tokenizable} instance.\n   *\n   * @remarks\n   * Optional — but required when `attachments` is absent or empty. The cross-field rule on\n   * `rawMessageSchema` enforces that at least one of `content` or `attachments` is present.\n   */\n  content?: string | Tokenizable\n  /**\n   * Media attachments carried by this message — images, audio, video, documents.\n   *\n   * @remarks\n   * Optional and symmetric across roles: both `user` and `assistant` messages may carry\n   * attachments. Each attachment carries its own `trustTier` and `modalityHazard`, which the\n   * renderer uses to wrap the asset in its own trust envelope independent of the message\n   * envelope. How a renderer orders text vs attachments in the on-the-wire content array is\n   * a renderer-policy concern, not a contract of {@link Message}.\n   */\n  attachments?: Media[]\n  /**\n   * The identity of the participant who authored this message.\n   *\n   * @remarks\n   * Optional. When omitted, the `role` value is used as both the system-facing `identifier`\n   * and the model-facing `representation`. Three accepted forms when provided:\n   * - A plain `string` — used as both `identifier` and `representation`.\n   * - A {@link @nhtio/adk!RawIdentity} object — validated and wrapped into an {@link @nhtio/adk!Identity}.\n   * - An existing {@link @nhtio/adk!Identity} instance — passed through unchanged.\n   */\n  identity?: string | RawIdentity | Identity\n  /** When this message was created. */\n  createdAt: string | number | Date | DateTime\n  /** When this message was last modified. */\n  updatedAt: string | number | Date | DateTime\n}\n\n/**\n * A fully-resolved {@link RawMessage} where temporal fields have been normalised to Luxon\n * `DateTime` instances and `identity` is a validated {@link @nhtio/adk!Identity}.\n *\n * @remarks\n * Used internally by the {@link Message} constructor to assign private fields with\n * guaranteed types.\n */\ninterface ResolvedMessage {\n  id: string\n  role: MessageRole\n  content?: Tokenizable\n  attachments: Media[]\n  identity: string | RawIdentity | Identity\n  createdAt: DateTime\n  updatedAt: DateTime\n}\n\n/**\n * Validator schema used to validate a {@link RawMessage} before constructing a {@link Message}.\n *\n * @remarks\n * Validates all fields of {@link RawMessage}:\n * - `id` — required non-empty string.\n * - `role` — required; must be `'user'` or `'assistant'`.\n * - `content` — optional string or {@link @nhtio/adk!Tokenizable}, via {@link @nhtio/adk!Tokenizable.schema}.\n * - `attachments` — optional array of {@link @nhtio/adk!Media} instances. Defaults to `[]`.\n * - At least one of `content` or `attachments` must be present and non-empty; a message with\n *   neither is invalid.\n * - `identity` — required string, {@link @nhtio/adk!RawIdentity}, or {@link @nhtio/adk!Identity}; a plain string is\n *   mapped to both `identifier` and `representation` automatically.\n * - `createdAt` / `updatedAt` — required datetime-parseable values, normalised to `DateTime`.\n *\n * Throws {@link @nhtio/adk!E_INVALID_INITIAL_MESSAGE_VALUE} (via the {@link Message} constructor) when\n * validation fails.\n */\nconst rawMessageSchema = validator\n  .object<RawMessage>({\n    id: validator.string().required(),\n    role: validator.string().valid('user', 'assistant').required(),\n    content: Tokenizable.schema.optional(),\n    attachments: validator\n      .array()\n      .items(\n        validator.any().custom((value, helpers) => {\n          if (Media.isMedia(value)) return value\n          return helpers.error('any.invalid')\n        })\n      )\n      .default([]),\n    identity: validator\n      .alternatives(validator.string(), Identity.schema)\n      .default(validator.ref('role')),\n    createdAt: validator.datetime().required(),\n    updatedAt: validator.datetime().required(),\n  })\n  .custom((value, helpers) => {\n    const resolved = value as ResolvedMessage\n    const hasContent = resolved.content !== undefined && resolved.content !== null\n    const hasAttachments = Array.isArray(resolved.attachments) && resolved.attachments.length > 0\n    if (!hasContent && !hasAttachments) {\n      return helpers.error('any.invalid')\n    }\n    return resolved\n  })\n\n/**\n * An immutable, validated conversation message from a human participant or the model.\n *\n * @remarks\n * Covers only `user` and `assistant` roles — system instructions, developer directives, and\n * tool results are not represented here. Constructed from a {@link RawMessage} via\n * `rawMessageSchema`. Temporal fields are normalised to Luxon `DateTime` instances at\n * construction time. Both `content` and `identity.representation` are {@link @nhtio/adk!Tokenizable} so\n * token cost can be estimated inline.\n *\n * A message may carry `content` (text), `attachments` (media), or both. The cross-field rule\n * on `rawMessageSchema` enforces that at least one is present. Downstream code that reaches\n * for `message.content` must handle the attachments-only case where `content` is `undefined`.\n */\nexport class Message {\n  /**\n   * Validator schema that accepts a {@link RawMessage} object.\n   *\n   * @remarks\n   * Reusable fragment for any schema that needs to validate or nest a message entry — for\n   * example, a collection schema that holds an array of messages.\n   */\n  public static schema = rawMessageSchema\n\n  /**\n   * Returns `true` if `value` is a {@link Message} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety — `instanceof` would fail for instances\n   * created in a different module copy or VM context.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is a {@link Message} instance.\n   */\n  public static isMessage(value: unknown): value is Message {\n    return isInstanceOf(value, 'Message', Message)\n  }\n\n  /** Stable unique identifier for this message. */\n  declare readonly id: string\n  /** Whether this message is from the human participant or the model. */\n  declare readonly role: MessageRole\n  /**\n   * The message content as a {@link @nhtio/adk!Tokenizable} for inline token estimation, or `undefined`\n   * for attachments-only messages.\n   *\n   * @remarks\n   * `undefined` when the message was constructed with only `attachments`. Render code that\n   * needs the text portion must guard for the missing case rather than blindly calling\n   * `message.content.toString()`.\n   */\n  declare readonly content: Tokenizable | undefined\n  /**\n   * Media attachments carried by this message.\n   *\n   * @remarks\n   * Always defined as a frozen array — empty when the message has no attachments. Both\n   * `user` and `assistant` messages may carry attachments. Each entry carries its own\n   * `trustTier` and `modalityHazard`; the renderer wraps each in its own trust envelope\n   * independent of the message envelope.\n   */\n  declare readonly attachments: ReadonlyArray<Media>\n  /** The identity of the participant who authored this message. */\n  declare readonly identity: Identity\n  /** When this message was created. */\n  declare readonly createdAt: DateTime\n  /** When this message was last modified. */\n  declare readonly updatedAt: DateTime\n\n  #id: string\n  #role: MessageRole\n  #content: Tokenizable | undefined\n  #attachments: ReadonlyArray<Media>\n  #identity: Identity\n  #createdAt: DateTime\n  #updatedAt: DateTime\n\n  /**\n   * @param raw - The raw message input validated against `rawMessageSchema`.\n   * @throws {@link @nhtio/adk!E_INVALID_INITIAL_MESSAGE_VALUE} when `raw` does not satisfy the schema —\n   *   including the cross-field rule that at least one of `content` or `attachments` must be\n   *   present and non-empty.\n   */\n  constructor(raw: RawMessage) {\n    let resolved: ResolvedMessage\n    try {\n      resolved = validateOrThrow<ResolvedMessage>(rawMessageSchema, raw, true)\n    } catch (err) {\n      throw new E_INVALID_INITIAL_MESSAGE_VALUE({ cause: isError(err) ? err : undefined })\n    }\n    this.#id = resolved.id\n    this.#role = resolved.role\n    this.#content =\n      resolved.content === undefined || resolved.content === null\n        ? undefined\n        : Tokenizable.isTokenizable(resolved.content)\n          ? resolved.content\n          : new Tokenizable(resolved.content)\n    this.#attachments = Object.freeze([...(resolved.attachments ?? [])])\n    const rawIdentity = resolved.identity\n    this.#identity = Identity.isIdentity(rawIdentity)\n      ? rawIdentity\n      : typeof rawIdentity === 'string'\n        ? new Identity({ identifier: rawIdentity, representation: rawIdentity })\n        : new Identity(rawIdentity)\n    this.#createdAt = resolved.createdAt\n    this.#updatedAt = resolved.updatedAt\n\n    Object.defineProperties(this, {\n      id: {\n        get: () => this.#id,\n        enumerable: true,\n        configurable: false,\n      },\n      role: {\n        get: () => this.#role,\n        enumerable: true,\n        configurable: false,\n      },\n      content: {\n        get: () => this.#content,\n        enumerable: true,\n        configurable: false,\n      },\n      attachments: {\n        get: () => this.#attachments,\n        enumerable: true,\n        configurable: false,\n      },\n      identity: {\n        get: () => this.#identity,\n        enumerable: true,\n        configurable: false,\n      },\n      createdAt: {\n        get: () => this.#createdAt,\n        enumerable: true,\n        configurable: false,\n      },\n      updatedAt: {\n        get: () => this.#updatedAt,\n        enumerable: true,\n        configurable: false,\n      },\n    })\n  }\n}\n","import { Identity } from './identity'\nimport { Tokenizable } from './tokenizable'\nimport { validator } from '@nhtio/validation'\nimport { validateOrThrow } from '../utils/validation'\nimport { isInstanceOf, isError } from '../utils/guards'\nimport { E_INVALID_INITIAL_THOUGHT_VALUE } from '../exceptions/runtime'\nimport type { DateTime } from 'luxon'\nimport type { RawIdentity } from './identity'\n\n/**\n * Plain input object supplied to {@link Thought} at construction time.\n *\n * @remarks\n * Validated against `rawThoughtSchema` before the `Thought` instance is created.\n * Temporal fields accept any value that Luxon can parse — ISO strings, Unix timestamps,\n * `Date` objects, or existing `DateTime` instances.\n */\nexport interface RawThought {\n  /** Stable unique identifier for this thought. */\n  id: string\n  /** The reasoning content as a plain string or an existing {@link @nhtio/adk!Tokenizable} instance. */\n  content: string | Tokenizable\n  /**\n   * The identity of the agent who produced this thought.\n   *\n   * @remarks\n   * Required in multi-agent conversations to attribute reasoning traces to a specific agent.\n   * Three accepted forms when provided:\n   * - A plain `string` — used as both `identifier` and `representation`.\n   * - A {@link @nhtio/adk!RawIdentity} object — validated and wrapped into an {@link @nhtio/adk!Identity}.\n   * - An existing {@link @nhtio/adk!Identity} instance — passed through unchanged.\n   *\n   * When omitted, defaults to `'assistant'` (both `identifier` and `representation`).\n   */\n  identity?: string | RawIdentity | Identity\n  /**\n   * Optional vendor-opaque payload that round-trips back to a matching model wire.\n   *\n   * @remarks\n   * Carries anything the ADK cannot interpret but a specific provider can — for example,\n   * an Anthropic Messages thinking-block `signature`, an OpenAI Responses\n   * `ResponseReasoningItem.encrypted_content` blob, a DeepSeek server-side reasoning handle,\n   * or an MCP-mediated reasoning item.\n   *\n   * When present, an LLM battery MUST treat the thought as **opaque-mode**: do NOT inline\n   * `content` through the plain `<thought>` envelope; serialise `payload` back to the wire in\n   * whichever shape the matching {@link RawThought.replayCompatibility} identifier specifies.\n   * The plain-text `content` is kept alongside for token-accounting and human/observer\n   * inspection — it is not the thing the model sees.\n   *\n   * Cross-field invariant: a present `payload` REQUIRES a present {@link RawThought.replayCompatibility}.\n   * A `payload` without `replayCompatibility` is malformed (the ADK has no way to know\n   * which adapter can consume it) and {@link Thought.schema} rejects with\n   * {@link @nhtio/adk!E_INVALID_INITIAL_THOUGHT_VALUE}.\n   *\n   * @defaultValue `undefined`\n   */\n  payload?: unknown\n  /**\n   * Optional free-form identifier describing which adapter wire-shape this thought can be\n   * safely replayed into.\n   *\n   * @remarks\n   * Examples (none of these are reserved by the ADK — they are consumer conventions):\n   *   - `'plain-text'` — replayable into every LLM battery\n   *   - `'anthropic-messages-thinking-v1'`\n   *   - `'openai-responses-reasoning-item-v1'`\n   *   - `'deepseek-reasoning-handle-v1'`\n   *\n   * LLM batteries declare via constructor option which tags they can safely replay; matching\n   * opaque thoughts are routed to the wire's typed reasoning channel where it exists, or to a\n   * documented side-channel key on the request body where the wire has none. Non-matching\n   * opaque thoughts are elided from the current dispatch but NOT removed from\n   * `ctx.turnThoughts` — they remain in context so a subsequent dispatch to a different\n   * adapter that DOES declare the matching tag can pick them up.\n   *\n   * Plain-text thoughts (`payload === undefined` AND `replayCompatibility === undefined`, or\n   * explicit `replayCompatibility: 'plain-text'`) are always replayable.\n   *\n   * A `replayCompatibility` without a `payload` is allowed — it documents intent (\"this\n   * plain-text thought is only meaningful to a specific fine-tuned variant\") without\n   * requiring an opaque blob.\n   *\n   * @defaultValue `undefined`\n   */\n  replayCompatibility?: string\n  /** When this thought was recorded. */\n  createdAt: string | number | Date | DateTime\n  /** When this thought was last modified. */\n  updatedAt: string | number | Date | DateTime\n}\n\n/**\n * A fully-resolved {@link RawThought} where temporal fields have been normalised to Luxon\n * `DateTime` instances.\n *\n * @remarks\n * Used internally by the {@link Thought} constructor to assign private fields with\n * guaranteed types.\n */\ninterface ResolvedThought {\n  id: string\n  content: Tokenizable\n  identity: string | RawIdentity | Identity\n  payload?: unknown\n  replayCompatibility?: string\n  createdAt: DateTime\n  updatedAt: DateTime\n}\n\n/**\n * Validator schema used to validate a {@link RawThought} before constructing a {@link Thought}.\n *\n * @remarks\n * Validates all fields of {@link RawThought}:\n * - `id` — required non-empty string.\n * - `content` — required string or {@link @nhtio/adk!Tokenizable}, via {@link @nhtio/adk!Tokenizable.schema}.\n * - `identity` — optional string, {@link @nhtio/adk!RawIdentity}, or {@link @nhtio/adk!Identity}; defaults to\n *   `'assistant'` when omitted.\n * - `createdAt` / `updatedAt` — required datetime-parseable values, normalised to `DateTime`.\n *\n * Throws {@link @nhtio/adk!E_INVALID_INITIAL_THOUGHT_VALUE} (via the {@link Thought} constructor) when\n * validation fails.\n */\nconst rawThoughtSchema = validator\n  .object<RawThought>({\n    id: validator.string().required(),\n    content: Tokenizable.schema.required(),\n    identity: validator.alternatives(validator.string(), Identity.schema).default('assistant'),\n    payload: validator.any().optional(),\n    replayCompatibility: validator.string().min(1).optional(),\n    createdAt: validator.datetime().required(),\n    updatedAt: validator.datetime().required(),\n  })\n  .custom((value, helpers) => {\n    const v = value as RawThought\n    if (\n      v.payload !== undefined &&\n      (v.replayCompatibility === undefined || v.replayCompatibility === null)\n    ) {\n      return helpers.error('any.invalid')\n    }\n    return value\n  })\n\n/**\n * An immutable, validated internal reasoning trace produced by an agent.\n *\n * @remarks\n * Represents an agent's internal thinking — distinct from {@link @nhtio/adk!Message} (which is part of\n * the visible conversation) and never shown to end users directly. Carries an `identity` so\n * reasoning traces can be attributed to a specific agent in multi-agent conversations.\n * Constructed from a {@link RawThought} via `rawThoughtSchema`. The `content` field is always\n * a {@link @nhtio/adk!Tokenizable} so token cost can be estimated inline.\n */\nexport class Thought {\n  /**\n   * Validator schema that accepts a {@link RawThought} object.\n   *\n   * @remarks\n   * Reusable fragment for any schema that needs to validate or nest a thought entry.\n   */\n  public static schema = rawThoughtSchema\n\n  /**\n   * Returns `true` if `value` is a {@link Thought} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety — `instanceof` would fail for instances\n   * created in a different module copy or VM context.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is a {@link Thought} instance.\n   */\n  public static isThought(value: unknown): value is Thought {\n    return isInstanceOf(value, 'Thought', Thought)\n  }\n\n  /** Stable unique identifier for this thought. */\n  declare readonly id: string\n  /** The reasoning content as a {@link @nhtio/adk!Tokenizable} for inline token estimation. */\n  declare readonly content: Tokenizable\n  /** The identity of the agent who produced this thought. */\n  declare readonly identity: Identity\n  /**\n   * Optional vendor-opaque payload that round-trips back to a matching model wire.\n   * See {@link RawThought.payload}.\n   */\n  declare readonly payload: unknown\n  /**\n   * Optional wire-shape identifier describing which adapter can safely replay this thought.\n   * See {@link RawThought.replayCompatibility}.\n   */\n  declare readonly replayCompatibility: string | undefined\n  /** When this thought was recorded. */\n  declare readonly createdAt: DateTime\n  /** When this thought was last modified. */\n  declare readonly updatedAt: DateTime\n\n  #id: string\n  #content: Tokenizable\n  #identity: Identity\n  #payload: unknown\n  #replayCompatibility: string | undefined\n  #createdAt: DateTime\n  #updatedAt: DateTime\n\n  /**\n   * @param raw - The raw thought input validated against `rawThoughtSchema`.\n   * @throws {@link @nhtio/adk!E_INVALID_INITIAL_THOUGHT_VALUE} when `raw` does not satisfy the schema.\n   */\n  constructor(raw: RawThought) {\n    let resolved: ResolvedThought\n    try {\n      resolved = validateOrThrow<ResolvedThought>(rawThoughtSchema, raw, true)\n    } catch (err) {\n      throw new E_INVALID_INITIAL_THOUGHT_VALUE({ cause: isError(err) ? err : undefined })\n    }\n    this.#id = resolved.id\n    this.#content = Tokenizable.isTokenizable(resolved.content)\n      ? resolved.content\n      : new Tokenizable(resolved.content)\n    const rawIdentity = resolved.identity\n    this.#identity = Identity.isIdentity(rawIdentity)\n      ? rawIdentity\n      : typeof rawIdentity === 'string'\n        ? new Identity({ identifier: rawIdentity, representation: rawIdentity })\n        : new Identity(rawIdentity)\n    this.#payload = resolved.payload\n    this.#replayCompatibility = resolved.replayCompatibility\n    this.#createdAt = resolved.createdAt\n    this.#updatedAt = resolved.updatedAt\n\n    Object.defineProperties(this, {\n      id: {\n        get: () => this.#id,\n        enumerable: true,\n        configurable: false,\n      },\n      content: {\n        get: () => this.#content,\n        enumerable: true,\n        configurable: false,\n      },\n      identity: {\n        get: () => this.#identity,\n        enumerable: true,\n        configurable: false,\n      },\n      payload: {\n        get: () => this.#payload,\n        enumerable: true,\n        configurable: false,\n      },\n      replayCompatibility: {\n        get: () => this.#replayCompatibility,\n        enumerable: true,\n        configurable: false,\n      },\n      createdAt: {\n        get: () => this.#createdAt,\n        enumerable: true,\n        configurable: false,\n      },\n      updatedAt: {\n        get: () => this.#updatedAt,\n        enumerable: true,\n        configurable: false,\n      },\n    })\n  }\n}\n"],"mappings":"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"}

package/{thought-D9IS11b5.mjs → thought-B_P8LiB6.mjs}

@@ -1,7 +1,7 @@
 import { a as validateOrThrow } from "./exceptions-BeWH2FwP.mjs";
-import { a as Tokenizable, o as isError, s as isInstanceOf } from "./tool_registry-CX3ofUh9.mjs";
-import { a as E_INVALID_INITIAL_MEMORY_VALUE, l as E_INVALID_INITIAL_THOUGHT_VALUE, o as E_INVALID_INITIAL_MESSAGE_VALUE, r as E_INVALID_INITIAL_IDENTITY_VALUE } from "./runtime-CDIZwCT0.mjs";
-import { n as Media } from "./tool_call-Bs_Q5LOG.mjs";
+import { a as Tokenizable, o as isError, s as isInstanceOf } from "./tool_registry-BGHg6KTq.mjs";
+import { a as E_INVALID_INITIAL_MEMORY_VALUE, l as E_INVALID_INITIAL_THOUGHT_VALUE, o as E_INVALID_INITIAL_MESSAGE_VALUE, r as E_INVALID_INITIAL_IDENTITY_VALUE } from "./runtime-j92CNi5z.mjs";
+import { n as Media } from "./tool_call-BUeMuCc6.mjs";
 import { validator } from "@nhtio/validation";
 //#region src/lib/classes/identity.ts
 /**
@@ -467,4 +467,4 @@ var Thought = class Thought {
 //#endregion
 export { Identity as i, Message as n, Memory as r, Thought as t };
 
-//# sourceMappingURL=thought-D9IS11b5.mjs.map
+//# sourceMappingURL=thought-B_P8LiB6.mjs.map

package/{thought-D9IS11b5.mjs.map → thought-B_P8LiB6.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"thought-D9IS11b5.mjs","names":["#identifier","#representation","#id","#content","#confidence","#importance","#createdAt","#updatedAt","#id","#role","#content","#attachments","#identity","#createdAt","#updatedAt","#id","#content","#identity","#payload","#replayCompatibility","#createdAt","#updatedAt"],"sources":["../src/lib/classes/identity.ts","../src/lib/classes/memory.ts","../src/lib/classes/message.ts","../src/lib/classes/thought.ts"],"sourcesContent":["import { Tokenizable } from './tokenizable'\nimport { validator } from '@nhtio/validation'\nimport { validateOrThrow } from '../utils/validation'\nimport { isInstanceOf, isError } from '../utils/guards'\nimport { E_INVALID_INITIAL_IDENTITY_VALUE } from '../exceptions/runtime'\n\n/**\n * Plain input object supplied to {@link Identity} at construction time.\n *\n * @remarks\n * Validated against `rawIdentitySchema` before the `Identity` instance is created.\n */\nexport interface RawIdentity {\n  /**\n   * The system-facing identifier for this participant.\n   *\n   * @remarks\n   * Used internally to correlate messages to a specific participant — e.g. a database ID or\n   * a username. Never sent to the model directly; use `representation` for that.\n   */\n  identifier: string | number\n  /**\n   * How this participant should be presented to the model.\n   *\n   * @remarks\n   * Accepts a plain string or an existing {@link @nhtio/adk!Tokenizable} instance. This is what the model\n   * sees when it needs to distinguish between participants of the same role.\n   */\n  representation: string | Tokenizable\n}\n\n/**\n * A fully-resolved {@link RawIdentity} where `representation` has been normalised to a\n * {@link @nhtio/adk!Tokenizable} instance.\n *\n * @remarks\n * Used internally by the {@link Identity} constructor to assign private fields with\n * guaranteed types.\n */\ninterface ResolvedIdentity {\n  identifier: string | number\n  representation: Tokenizable\n}\n\n/**\n * Validator schema used to validate a {@link RawIdentity} before constructing an {@link Identity}.\n *\n * @remarks\n * Validates both fields of {@link RawIdentity}:\n * - `identifier` — required string or number.\n * - `representation` — required string or {@link @nhtio/adk!Tokenizable}, via {@link @nhtio/adk!Tokenizable.schema}.\n *\n * Throws {@link @nhtio/adk!E_INVALID_INITIAL_IDENTITY_VALUE} (via the {@link Identity} constructor) when\n * validation fails.\n */\nconst rawIdentitySchema = validator.object<RawIdentity>({\n  identifier: validator.alternatives(validator.string(), validator.number()).required(),\n  representation: Tokenizable.schema.required(),\n})\n\n/**\n * An immutable, validated participant identity attached to a {@link @nhtio/adk!Message}.\n *\n * @remarks\n * Carries two distinct representations of the same participant: `identifier` is the\n * system-facing key (e.g. a database ID) used to correlate messages programmatically;\n * `representation` is what the model sees when it needs to distinguish between participants\n * sharing the same role. The `representation` is always a {@link @nhtio/adk!Tokenizable} so token cost\n * can be estimated inline.\n */\nexport class Identity {\n  /**\n   * Validator schema that accepts a {@link RawIdentity} object.\n   *\n   * @remarks\n   * Reusable fragment for any schema that needs to validate or nest an identity — for example,\n   * as a required field inside a message schema.\n   */\n  public static schema = rawIdentitySchema\n\n  /**\n   * Returns `true` if `value` is an {@link Identity} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety — `instanceof` would fail for instances\n   * created in a different module copy or VM context.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is an {@link Identity} instance.\n   */\n  public static isIdentity(value: unknown): value is Identity {\n    return isInstanceOf(value, 'Identity', Identity)\n  }\n\n  /**\n   * The system-facing identifier for this participant — never sent to the model directly.\n   */\n  declare readonly identifier: string | number\n\n  /**\n   * How this participant is presented to the model, as a {@link @nhtio/adk!Tokenizable} for inline\n   * token estimation.\n   */\n  declare readonly representation: Tokenizable\n\n  #identifier: string | number\n  #representation: Tokenizable\n\n  /**\n   * @param raw - The raw identity input validated against `rawIdentitySchema`.\n   * @throws {@link @nhtio/adk!E_INVALID_INITIAL_IDENTITY_VALUE} when `raw` does not satisfy the schema.\n   */\n  constructor(raw: RawIdentity) {\n    let resolved: ResolvedIdentity\n    try {\n      resolved = validateOrThrow<ResolvedIdentity>(rawIdentitySchema, raw, true)\n    } catch (err) {\n      throw new E_INVALID_INITIAL_IDENTITY_VALUE({ cause: isError(err) ? err : undefined })\n    }\n    this.#identifier = resolved.identifier\n    this.#representation = Tokenizable.isTokenizable(resolved.representation)\n      ? resolved.representation\n      : new Tokenizable(resolved.representation)\n\n    Object.defineProperties(this, {\n      identifier: {\n        get: () => this.#identifier,\n        enumerable: true,\n        configurable: false,\n      },\n      representation: {\n        get: () => this.#representation,\n        enumerable: true,\n        configurable: false,\n      },\n    })\n  }\n}\n","import { Tokenizable } from './tokenizable'\nimport { validator } from '@nhtio/validation'\nimport { validateOrThrow } from '../utils/validation'\nimport { isInstanceOf, isError } from '../utils/guards'\nimport { E_INVALID_INITIAL_MEMORY_VALUE } from '../exceptions/runtime'\nimport type { DateTime } from 'luxon'\n\n/**\n * Plain input object supplied to {@link Memory} at construction time.\n *\n * @remarks\n * Validated against `rawMemorySchema` before the `Memory` instance is created.\n * Temporal fields accept any value that Luxon can parse — ISO strings, Unix timestamps,\n * `Date` objects, or existing `DateTime` instances.\n */\nexport interface RawMemory {\n  /** Stable unique identifier for this memory entry. */\n  id: string\n  /** The memory content as a plain string or an existing {@link @nhtio/adk!Tokenizable} instance. */\n  content: string | Tokenizable\n  /** Confidence score in the range `[0, 1]` — how certain the agent is that this memory is accurate. */\n  confidence: number\n  /** Importance score in the range `[0, 1]` — how much weight this memory should carry during retrieval. */\n  importance: number\n  /** When this memory was first recorded. */\n  createdAt: string | number | Date | DateTime\n  /** When this memory was last modified. */\n  updatedAt: string | number | Date | DateTime\n}\n\n/**\n * A fully-resolved {@link RawMemory} where all fields have been validated and temporal values\n * normalised to Luxon `DateTime` instances.\n *\n * @remarks\n * This is the shape returned by `rawMemorySchema` after validation — used internally by the\n * {@link Memory} constructor to assign private fields with guaranteed types.\n */\ninterface ResolvedMemory {\n  id: string\n  content: Tokenizable\n  confidence: number\n  importance: number\n  createdAt: DateTime\n  updatedAt: DateTime\n}\n\n/**\n * Validator schema used to validate a {@link RawMemory} before constructing a {@link Memory}.\n *\n * @remarks\n * Validates all six fields of {@link RawMemory}:\n * - `id` — required non-empty string.\n * - `content` — required string or {@link @nhtio/adk!Tokenizable}, via {@link @nhtio/adk!Tokenizable.schema}.\n * - `confidence` — required number in `[0, 1]`.\n * - `importance` — required number in `[0, 1]`.\n * - `createdAt` / `updatedAt` — required datetime-parseable values, normalised to `DateTime`.\n *\n * Throws {@link @nhtio/adk!E_INVALID_INITIAL_MEMORY_VALUE} (via the {@link Memory} constructor) when\n * validation fails.\n */\nconst rawMemorySchema = validator.object<RawMemory>({\n  id: validator.string().required(),\n  content: Tokenizable.schema.required(),\n  confidence: validator.number().min(0).max(1).required(),\n  importance: validator.number().min(0).max(1).required(),\n  createdAt: validator.datetime().required(),\n  updatedAt: validator.datetime().required(),\n})\n\n/**\n * An immutable, validated memory entry held by the agent.\n *\n * @remarks\n * Constructed from a {@link RawMemory} via `rawMemorySchema`. All temporal fields are\n * normalised to Luxon `DateTime` instances at construction time. The `content` field is\n * always a {@link @nhtio/adk!Tokenizable} so callers can estimate token cost without an additional\n * wrapping step.\n */\nexport class Memory {\n  /**\n   * Validator schema that accepts a {@link RawMemory} object.\n   *\n   * @remarks\n   * Reusable fragment for any schema that needs to validate or nest a memory entry — for\n   * example, a collection schema that holds an array of memories.\n   */\n  public static schema = rawMemorySchema\n\n  /**\n   * Returns `true` if `value` is a {@link Memory} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety — `instanceof` would fail for instances\n   * created in a different module copy or VM context.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is a {@link Memory} instance.\n   */\n  public static isMemory(value: unknown): value is Memory {\n    return isInstanceOf(value, 'Memory', Memory)\n  }\n  /** Stable unique identifier for this memory entry. */\n  declare readonly id: string\n  /** The memory content as a {@link @nhtio/adk!Tokenizable} for inline token estimation. */\n  declare readonly content: Tokenizable\n  /** Confidence score in the range `[0, 1]`. */\n  declare readonly confidence: number\n  /** Importance score in the range `[0, 1]`. */\n  declare readonly importance: number\n  /** When this memory was first recorded. */\n  declare readonly createdAt: DateTime\n  /** When this memory was last modified. */\n  declare readonly updatedAt: DateTime\n\n  #id: string\n  #content: Tokenizable\n  #confidence: number\n  #importance: number\n  #createdAt: DateTime\n  #updatedAt: DateTime\n\n  /**\n   * @param raw - The raw memory input validated against `rawMemorySchema`.\n   * @throws {@link @nhtio/adk!E_INVALID_INITIAL_MEMORY_VALUE} when `raw` does not satisfy the schema.\n   */\n  constructor(raw: RawMemory) {\n    let resolved: ResolvedMemory\n    try {\n      resolved = validateOrThrow<ResolvedMemory>(rawMemorySchema, raw, true)\n    } catch (err) {\n      throw new E_INVALID_INITIAL_MEMORY_VALUE({ cause: isError(err) ? err : undefined })\n    }\n    this.#id = resolved.id\n    this.#content = Tokenizable.isTokenizable(resolved.content)\n      ? resolved.content\n      : new Tokenizable(resolved.content)\n    this.#confidence = resolved.confidence\n    this.#importance = resolved.importance\n    this.#createdAt = resolved.createdAt\n    this.#updatedAt = resolved.updatedAt\n\n    Object.defineProperties(this, {\n      id: {\n        get: () => this.#id,\n        enumerable: true,\n        configurable: false,\n      },\n      content: {\n        get: () => this.#content,\n        enumerable: true,\n        configurable: false,\n      },\n      confidence: {\n        get: () => this.#confidence,\n        enumerable: true,\n        configurable: false,\n      },\n      importance: {\n        get: () => this.#importance,\n        enumerable: true,\n        configurable: false,\n      },\n      createdAt: {\n        get: () => this.#createdAt,\n        enumerable: true,\n        configurable: false,\n      },\n      updatedAt: {\n        get: () => this.#updatedAt,\n        enumerable: true,\n        configurable: false,\n      },\n    })\n  }\n}\n","import { Media } from './media'\nimport { Identity } from './identity'\nimport { Tokenizable } from './tokenizable'\nimport { validator } from '@nhtio/validation'\nimport { validateOrThrow } from '../utils/validation'\nimport { isInstanceOf, isError } from '../utils/guards'\nimport { E_INVALID_INITIAL_MESSAGE_VALUE } from '../exceptions/runtime'\nimport type { DateTime } from 'luxon'\nimport type { RawIdentity } from './identity'\n\n/**\n * The roles a {@link Message} author can hold.\n *\n * @remarks\n * Restricted to `user` and `assistant` — system instructions, developer directives, and\n * tool results are handled separately and never appear in the persisted message history.\n */\nexport type MessageRole = 'user' | 'assistant'\n\n/**\n * Plain input object supplied to {@link Message} at construction time.\n *\n * @remarks\n * Validated against `rawMessageSchema` before the `Message` instance is created.\n * Temporal fields accept any value that Luxon can parse — ISO strings, Unix timestamps,\n * `Date` objects, or existing `DateTime` instances.\n *\n * At least one of `content` or `attachments` (non-empty) must be present — a message with\n * neither throws {@link @nhtio/adk!E_INVALID_INITIAL_MESSAGE_VALUE}.\n */\nexport interface RawMessage {\n  /** Stable unique identifier for this message. */\n  id: string\n  /** Whether this message is from the human participant or the model. */\n  role: MessageRole\n  /**\n   * The message content as a plain string or an existing {@link @nhtio/adk!Tokenizable} instance.\n   *\n   * @remarks\n   * Optional — but required when `attachments` is absent or empty. The cross-field rule on\n   * `rawMessageSchema` enforces that at least one of `content` or `attachments` is present.\n   */\n  content?: string | Tokenizable\n  /**\n   * Media attachments carried by this message — images, audio, video, documents.\n   *\n   * @remarks\n   * Optional and symmetric across roles: both `user` and `assistant` messages may carry\n   * attachments. Each attachment carries its own `trustTier` and `modalityHazard`, which the\n   * renderer uses to wrap the asset in its own trust envelope independent of the message\n   * envelope. How a renderer orders text vs attachments in the on-the-wire content array is\n   * a renderer-policy concern, not a contract of {@link Message}.\n   */\n  attachments?: Media[]\n  /**\n   * The identity of the participant who authored this message.\n   *\n   * @remarks\n   * Optional. When omitted, the `role` value is used as both the system-facing `identifier`\n   * and the model-facing `representation`. Three accepted forms when provided:\n   * - A plain `string` — used as both `identifier` and `representation`.\n   * - A {@link @nhtio/adk!RawIdentity} object — validated and wrapped into an {@link @nhtio/adk!Identity}.\n   * - An existing {@link @nhtio/adk!Identity} instance — passed through unchanged.\n   */\n  identity?: string | RawIdentity | Identity\n  /** When this message was created. */\n  createdAt: string | number | Date | DateTime\n  /** When this message was last modified. */\n  updatedAt: string | number | Date | DateTime\n}\n\n/**\n * A fully-resolved {@link RawMessage} where temporal fields have been normalised to Luxon\n * `DateTime` instances and `identity` is a validated {@link @nhtio/adk!Identity}.\n *\n * @remarks\n * Used internally by the {@link Message} constructor to assign private fields with\n * guaranteed types.\n */\ninterface ResolvedMessage {\n  id: string\n  role: MessageRole\n  content?: Tokenizable\n  attachments: Media[]\n  identity: string | RawIdentity | Identity\n  createdAt: DateTime\n  updatedAt: DateTime\n}\n\n/**\n * Validator schema used to validate a {@link RawMessage} before constructing a {@link Message}.\n *\n * @remarks\n * Validates all fields of {@link RawMessage}:\n * - `id` — required non-empty string.\n * - `role` — required; must be `'user'` or `'assistant'`.\n * - `content` — optional string or {@link @nhtio/adk!Tokenizable}, via {@link @nhtio/adk!Tokenizable.schema}.\n * - `attachments` — optional array of {@link @nhtio/adk!Media} instances. Defaults to `[]`.\n * - At least one of `content` or `attachments` must be present and non-empty; a message with\n *   neither is invalid.\n * - `identity` — required string, {@link @nhtio/adk!RawIdentity}, or {@link @nhtio/adk!Identity}; a plain string is\n *   mapped to both `identifier` and `representation` automatically.\n * - `createdAt` / `updatedAt` — required datetime-parseable values, normalised to `DateTime`.\n *\n * Throws {@link @nhtio/adk!E_INVALID_INITIAL_MESSAGE_VALUE} (via the {@link Message} constructor) when\n * validation fails.\n */\nconst rawMessageSchema = validator\n  .object<RawMessage>({\n    id: validator.string().required(),\n    role: validator.string().valid('user', 'assistant').required(),\n    content: Tokenizable.schema.optional(),\n    attachments: validator\n      .array()\n      .items(\n        validator.any().custom((value, helpers) => {\n          if (Media.isMedia(value)) return value\n          return helpers.error('any.invalid')\n        })\n      )\n      .default([]),\n    identity: validator\n      .alternatives(validator.string(), Identity.schema)\n      .default(validator.ref('role')),\n    createdAt: validator.datetime().required(),\n    updatedAt: validator.datetime().required(),\n  })\n  .custom((value, helpers) => {\n    const resolved = value as ResolvedMessage\n    const hasContent = resolved.content !== undefined && resolved.content !== null\n    const hasAttachments = Array.isArray(resolved.attachments) && resolved.attachments.length > 0\n    if (!hasContent && !hasAttachments) {\n      return helpers.error('any.invalid')\n    }\n    return resolved\n  })\n\n/**\n * An immutable, validated conversation message from a human participant or the model.\n *\n * @remarks\n * Covers only `user` and `assistant` roles — system instructions, developer directives, and\n * tool results are not represented here. Constructed from a {@link RawMessage} via\n * `rawMessageSchema`. Temporal fields are normalised to Luxon `DateTime` instances at\n * construction time. Both `content` and `identity.representation` are {@link @nhtio/adk!Tokenizable} so\n * token cost can be estimated inline.\n *\n * A message may carry `content` (text), `attachments` (media), or both. The cross-field rule\n * on `rawMessageSchema` enforces that at least one is present. Downstream code that reaches\n * for `message.content` must handle the attachments-only case where `content` is `undefined`.\n */\nexport class Message {\n  /**\n   * Validator schema that accepts a {@link RawMessage} object.\n   *\n   * @remarks\n   * Reusable fragment for any schema that needs to validate or nest a message entry — for\n   * example, a collection schema that holds an array of messages.\n   */\n  public static schema = rawMessageSchema\n\n  /**\n   * Returns `true` if `value` is a {@link Message} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety — `instanceof` would fail for instances\n   * created in a different module copy or VM context.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is a {@link Message} instance.\n   */\n  public static isMessage(value: unknown): value is Message {\n    return isInstanceOf(value, 'Message', Message)\n  }\n\n  /** Stable unique identifier for this message. */\n  declare readonly id: string\n  /** Whether this message is from the human participant or the model. */\n  declare readonly role: MessageRole\n  /**\n   * The message content as a {@link @nhtio/adk!Tokenizable} for inline token estimation, or `undefined`\n   * for attachments-only messages.\n   *\n   * @remarks\n   * `undefined` when the message was constructed with only `attachments`. Render code that\n   * needs the text portion must guard for the missing case rather than blindly calling\n   * `message.content.toString()`.\n   */\n  declare readonly content: Tokenizable | undefined\n  /**\n   * Media attachments carried by this message.\n   *\n   * @remarks\n   * Always defined as a frozen array — empty when the message has no attachments. Both\n   * `user` and `assistant` messages may carry attachments. Each entry carries its own\n   * `trustTier` and `modalityHazard`; the renderer wraps each in its own trust envelope\n   * independent of the message envelope.\n   */\n  declare readonly attachments: ReadonlyArray<Media>\n  /** The identity of the participant who authored this message. */\n  declare readonly identity: Identity\n  /** When this message was created. */\n  declare readonly createdAt: DateTime\n  /** When this message was last modified. */\n  declare readonly updatedAt: DateTime\n\n  #id: string\n  #role: MessageRole\n  #content: Tokenizable | undefined\n  #attachments: ReadonlyArray<Media>\n  #identity: Identity\n  #createdAt: DateTime\n  #updatedAt: DateTime\n\n  /**\n   * @param raw - The raw message input validated against `rawMessageSchema`.\n   * @throws {@link @nhtio/adk!E_INVALID_INITIAL_MESSAGE_VALUE} when `raw` does not satisfy the schema —\n   *   including the cross-field rule that at least one of `content` or `attachments` must be\n   *   present and non-empty.\n   */\n  constructor(raw: RawMessage) {\n    let resolved: ResolvedMessage\n    try {\n      resolved = validateOrThrow<ResolvedMessage>(rawMessageSchema, raw, true)\n    } catch (err) {\n      throw new E_INVALID_INITIAL_MESSAGE_VALUE({ cause: isError(err) ? err : undefined })\n    }\n    this.#id = resolved.id\n    this.#role = resolved.role\n    this.#content =\n      resolved.content === undefined || resolved.content === null\n        ? undefined\n        : Tokenizable.isTokenizable(resolved.content)\n          ? resolved.content\n          : new Tokenizable(resolved.content)\n    this.#attachments = Object.freeze([...(resolved.attachments ?? [])])\n    const rawIdentity = resolved.identity\n    this.#identity = Identity.isIdentity(rawIdentity)\n      ? rawIdentity\n      : typeof rawIdentity === 'string'\n        ? new Identity({ identifier: rawIdentity, representation: rawIdentity })\n        : new Identity(rawIdentity)\n    this.#createdAt = resolved.createdAt\n    this.#updatedAt = resolved.updatedAt\n\n    Object.defineProperties(this, {\n      id: {\n        get: () => this.#id,\n        enumerable: true,\n        configurable: false,\n      },\n      role: {\n        get: () => this.#role,\n        enumerable: true,\n        configurable: false,\n      },\n      content: {\n        get: () => this.#content,\n        enumerable: true,\n        configurable: false,\n      },\n      attachments: {\n        get: () => this.#attachments,\n        enumerable: true,\n        configurable: false,\n      },\n      identity: {\n        get: () => this.#identity,\n        enumerable: true,\n        configurable: false,\n      },\n      createdAt: {\n        get: () => this.#createdAt,\n        enumerable: true,\n        configurable: false,\n      },\n      updatedAt: {\n        get: () => this.#updatedAt,\n        enumerable: true,\n        configurable: false,\n      },\n    })\n  }\n}\n","import { Identity } from './identity'\nimport { Tokenizable } from './tokenizable'\nimport { validator } from '@nhtio/validation'\nimport { validateOrThrow } from '../utils/validation'\nimport { isInstanceOf, isError } from '../utils/guards'\nimport { E_INVALID_INITIAL_THOUGHT_VALUE } from '../exceptions/runtime'\nimport type { DateTime } from 'luxon'\nimport type { RawIdentity } from './identity'\n\n/**\n * Plain input object supplied to {@link Thought} at construction time.\n *\n * @remarks\n * Validated against `rawThoughtSchema` before the `Thought` instance is created.\n * Temporal fields accept any value that Luxon can parse — ISO strings, Unix timestamps,\n * `Date` objects, or existing `DateTime` instances.\n */\nexport interface RawThought {\n  /** Stable unique identifier for this thought. */\n  id: string\n  /** The reasoning content as a plain string or an existing {@link @nhtio/adk!Tokenizable} instance. */\n  content: string | Tokenizable\n  /**\n   * The identity of the agent who produced this thought.\n   *\n   * @remarks\n   * Required in multi-agent conversations to attribute reasoning traces to a specific agent.\n   * Three accepted forms when provided:\n   * - A plain `string` — used as both `identifier` and `representation`.\n   * - A {@link @nhtio/adk!RawIdentity} object — validated and wrapped into an {@link @nhtio/adk!Identity}.\n   * - An existing {@link @nhtio/adk!Identity} instance — passed through unchanged.\n   *\n   * When omitted, defaults to `'assistant'` (both `identifier` and `representation`).\n   */\n  identity?: string | RawIdentity | Identity\n  /**\n   * Optional vendor-opaque payload that round-trips back to a matching model wire.\n   *\n   * @remarks\n   * Carries anything the ADK cannot interpret but a specific provider can — for example,\n   * an Anthropic Messages thinking-block `signature`, an OpenAI Responses\n   * `ResponseReasoningItem.encrypted_content` blob, a DeepSeek server-side reasoning handle,\n   * or an MCP-mediated reasoning item.\n   *\n   * When present, an LLM battery MUST treat the thought as **opaque-mode**: do NOT inline\n   * `content` through the plain `<thought>` envelope; serialise `payload` back to the wire in\n   * whichever shape the matching {@link RawThought.replayCompatibility} identifier specifies.\n   * The plain-text `content` is kept alongside for token-accounting and human/observer\n   * inspection — it is not the thing the model sees.\n   *\n   * Cross-field invariant: a present `payload` REQUIRES a present {@link RawThought.replayCompatibility}.\n   * A `payload` without `replayCompatibility` is malformed (the ADK has no way to know\n   * which adapter can consume it) and {@link Thought.schema} rejects with\n   * {@link @nhtio/adk!E_INVALID_INITIAL_THOUGHT_VALUE}.\n   *\n   * @defaultValue `undefined`\n   */\n  payload?: unknown\n  /**\n   * Optional free-form identifier describing which adapter wire-shape this thought can be\n   * safely replayed into.\n   *\n   * @remarks\n   * Examples (none of these are reserved by the ADK — they are consumer conventions):\n   *   - `'plain-text'` — replayable into every LLM battery\n   *   - `'anthropic-messages-thinking-v1'`\n   *   - `'openai-responses-reasoning-item-v1'`\n   *   - `'deepseek-reasoning-handle-v1'`\n   *\n   * LLM batteries declare via constructor option which tags they can safely replay; matching\n   * opaque thoughts are routed to the wire's typed reasoning channel where it exists, or to a\n   * documented side-channel key on the request body where the wire has none. Non-matching\n   * opaque thoughts are elided from the current dispatch but NOT removed from\n   * `ctx.turnThoughts` — they remain in context so a subsequent dispatch to a different\n   * adapter that DOES declare the matching tag can pick them up.\n   *\n   * Plain-text thoughts (`payload === undefined` AND `replayCompatibility === undefined`, or\n   * explicit `replayCompatibility: 'plain-text'`) are always replayable.\n   *\n   * A `replayCompatibility` without a `payload` is allowed — it documents intent (\"this\n   * plain-text thought is only meaningful to a specific fine-tuned variant\") without\n   * requiring an opaque blob.\n   *\n   * @defaultValue `undefined`\n   */\n  replayCompatibility?: string\n  /** When this thought was recorded. */\n  createdAt: string | number | Date | DateTime\n  /** When this thought was last modified. */\n  updatedAt: string | number | Date | DateTime\n}\n\n/**\n * A fully-resolved {@link RawThought} where temporal fields have been normalised to Luxon\n * `DateTime` instances.\n *\n * @remarks\n * Used internally by the {@link Thought} constructor to assign private fields with\n * guaranteed types.\n */\ninterface ResolvedThought {\n  id: string\n  content: Tokenizable\n  identity: string | RawIdentity | Identity\n  payload?: unknown\n  replayCompatibility?: string\n  createdAt: DateTime\n  updatedAt: DateTime\n}\n\n/**\n * Validator schema used to validate a {@link RawThought} before constructing a {@link Thought}.\n *\n * @remarks\n * Validates all fields of {@link RawThought}:\n * - `id` — required non-empty string.\n * - `content` — required string or {@link @nhtio/adk!Tokenizable}, via {@link @nhtio/adk!Tokenizable.schema}.\n * - `identity` — optional string, {@link @nhtio/adk!RawIdentity}, or {@link @nhtio/adk!Identity}; defaults to\n *   `'assistant'` when omitted.\n * - `createdAt` / `updatedAt` — required datetime-parseable values, normalised to `DateTime`.\n *\n * Throws {@link @nhtio/adk!E_INVALID_INITIAL_THOUGHT_VALUE} (via the {@link Thought} constructor) when\n * validation fails.\n */\nconst rawThoughtSchema = validator\n  .object<RawThought>({\n    id: validator.string().required(),\n    content: Tokenizable.schema.required(),\n    identity: validator.alternatives(validator.string(), Identity.schema).default('assistant'),\n    payload: validator.any().optional(),\n    replayCompatibility: validator.string().min(1).optional(),\n    createdAt: validator.datetime().required(),\n    updatedAt: validator.datetime().required(),\n  })\n  .custom((value, helpers) => {\n    const v = value as RawThought\n    if (\n      v.payload !== undefined &&\n      (v.replayCompatibility === undefined || v.replayCompatibility === null)\n    ) {\n      return helpers.error('any.invalid')\n    }\n    return value\n  })\n\n/**\n * An immutable, validated internal reasoning trace produced by an agent.\n *\n * @remarks\n * Represents an agent's internal thinking — distinct from {@link @nhtio/adk!Message} (which is part of\n * the visible conversation) and never shown to end users directly. Carries an `identity` so\n * reasoning traces can be attributed to a specific agent in multi-agent conversations.\n * Constructed from a {@link RawThought} via `rawThoughtSchema`. The `content` field is always\n * a {@link @nhtio/adk!Tokenizable} so token cost can be estimated inline.\n */\nexport class Thought {\n  /**\n   * Validator schema that accepts a {@link RawThought} object.\n   *\n   * @remarks\n   * Reusable fragment for any schema that needs to validate or nest a thought entry.\n   */\n  public static schema = rawThoughtSchema\n\n  /**\n   * Returns `true` if `value` is a {@link Thought} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety — `instanceof` would fail for instances\n   * created in a different module copy or VM context.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is a {@link Thought} instance.\n   */\n  public static isThought(value: unknown): value is Thought {\n    return isInstanceOf(value, 'Thought', Thought)\n  }\n\n  /** Stable unique identifier for this thought. */\n  declare readonly id: string\n  /** The reasoning content as a {@link @nhtio/adk!Tokenizable} for inline token estimation. */\n  declare readonly content: Tokenizable\n  /** The identity of the agent who produced this thought. */\n  declare readonly identity: Identity\n  /**\n   * Optional vendor-opaque payload that round-trips back to a matching model wire.\n   * See {@link RawThought.payload}.\n   */\n  declare readonly payload: unknown\n  /**\n   * Optional wire-shape identifier describing which adapter can safely replay this thought.\n   * See {@link RawThought.replayCompatibility}.\n   */\n  declare readonly replayCompatibility: string | undefined\n  /** When this thought was recorded. */\n  declare readonly createdAt: DateTime\n  /** When this thought was last modified. */\n  declare readonly updatedAt: DateTime\n\n  #id: string\n  #content: Tokenizable\n  #identity: Identity\n  #payload: unknown\n  #replayCompatibility: string | undefined\n  #createdAt: DateTime\n  #updatedAt: DateTime\n\n  /**\n   * @param raw - The raw thought input validated against `rawThoughtSchema`.\n   * @throws {@link @nhtio/adk!E_INVALID_INITIAL_THOUGHT_VALUE} when `raw` does not satisfy the schema.\n   */\n  constructor(raw: RawThought) {\n    let resolved: ResolvedThought\n    try {\n      resolved = validateOrThrow<ResolvedThought>(rawThoughtSchema, raw, true)\n    } catch (err) {\n      throw new E_INVALID_INITIAL_THOUGHT_VALUE({ cause: isError(err) ? err : undefined })\n    }\n    this.#id = resolved.id\n    this.#content = Tokenizable.isTokenizable(resolved.content)\n      ? resolved.content\n      : new Tokenizable(resolved.content)\n    const rawIdentity = resolved.identity\n    this.#identity = Identity.isIdentity(rawIdentity)\n      ? rawIdentity\n      : typeof rawIdentity === 'string'\n        ? new Identity({ identifier: rawIdentity, representation: rawIdentity })\n        : new Identity(rawIdentity)\n    this.#payload = resolved.payload\n    this.#replayCompatibility = resolved.replayCompatibility\n    this.#createdAt = resolved.createdAt\n    this.#updatedAt = resolved.updatedAt\n\n    Object.defineProperties(this, {\n      id: {\n        get: () => this.#id,\n        enumerable: true,\n        configurable: false,\n      },\n      content: {\n        get: () => this.#content,\n        enumerable: true,\n        configurable: false,\n      },\n      identity: {\n        get: () => this.#identity,\n        enumerable: true,\n        configurable: false,\n      },\n      payload: {\n        get: () => this.#payload,\n        enumerable: true,\n        configurable: false,\n      },\n      replayCompatibility: {\n        get: () => this.#replayCompatibility,\n        enumerable: true,\n        configurable: false,\n      },\n      createdAt: {\n        get: () => this.#createdAt,\n        enumerable: true,\n        configurable: false,\n      },\n      updatedAt: {\n        get: () => this.#updatedAt,\n        enumerable: true,\n        configurable: false,\n      },\n    })\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"thought-B_P8LiB6.mjs","names":["#identifier","#representation","#id","#content","#confidence","#importance","#createdAt","#updatedAt","#id","#role","#content","#attachments","#identity","#createdAt","#updatedAt","#id","#content","#identity","#payload","#replayCompatibility","#createdAt","#updatedAt"],"sources":["../src/lib/classes/identity.ts","../src/lib/classes/memory.ts","../src/lib/classes/message.ts","../src/lib/classes/thought.ts"],"sourcesContent":["import { Tokenizable } from './tokenizable'\nimport { validator } from '@nhtio/validation'\nimport { validateOrThrow } from '../utils/validation'\nimport { isInstanceOf, isError } from '../utils/guards'\nimport { E_INVALID_INITIAL_IDENTITY_VALUE } from '../exceptions/runtime'\n\n/**\n * Plain input object supplied to {@link Identity} at construction time.\n *\n * @remarks\n * Validated against `rawIdentitySchema` before the `Identity` instance is created.\n */\nexport interface RawIdentity {\n  /**\n   * The system-facing identifier for this participant.\n   *\n   * @remarks\n   * Used internally to correlate messages to a specific participant — e.g. a database ID or\n   * a username. Never sent to the model directly; use `representation` for that.\n   */\n  identifier: string | number\n  /**\n   * How this participant should be presented to the model.\n   *\n   * @remarks\n   * Accepts a plain string or an existing {@link @nhtio/adk!Tokenizable} instance. This is what the model\n   * sees when it needs to distinguish between participants of the same role.\n   */\n  representation: string | Tokenizable\n}\n\n/**\n * A fully-resolved {@link RawIdentity} where `representation` has been normalised to a\n * {@link @nhtio/adk!Tokenizable} instance.\n *\n * @remarks\n * Used internally by the {@link Identity} constructor to assign private fields with\n * guaranteed types.\n */\ninterface ResolvedIdentity {\n  identifier: string | number\n  representation: Tokenizable\n}\n\n/**\n * Validator schema used to validate a {@link RawIdentity} before constructing an {@link Identity}.\n *\n * @remarks\n * Validates both fields of {@link RawIdentity}:\n * - `identifier` — required string or number.\n * - `representation` — required string or {@link @nhtio/adk!Tokenizable}, via {@link @nhtio/adk!Tokenizable.schema}.\n *\n * Throws {@link @nhtio/adk!E_INVALID_INITIAL_IDENTITY_VALUE} (via the {@link Identity} constructor) when\n * validation fails.\n */\nconst rawIdentitySchema = validator.object<RawIdentity>({\n  identifier: validator.alternatives(validator.string(), validator.number()).required(),\n  representation: Tokenizable.schema.required(),\n})\n\n/**\n * An immutable, validated participant identity attached to a {@link @nhtio/adk!Message}.\n *\n * @remarks\n * Carries two distinct representations of the same participant: `identifier` is the\n * system-facing key (e.g. a database ID) used to correlate messages programmatically;\n * `representation` is what the model sees when it needs to distinguish between participants\n * sharing the same role. The `representation` is always a {@link @nhtio/adk!Tokenizable} so token cost\n * can be estimated inline.\n */\nexport class Identity {\n  /**\n   * Validator schema that accepts a {@link RawIdentity} object.\n   *\n   * @remarks\n   * Reusable fragment for any schema that needs to validate or nest an identity — for example,\n   * as a required field inside a message schema.\n   */\n  public static schema = rawIdentitySchema\n\n  /**\n   * Returns `true` if `value` is an {@link Identity} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety — `instanceof` would fail for instances\n   * created in a different module copy or VM context.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is an {@link Identity} instance.\n   */\n  public static isIdentity(value: unknown): value is Identity {\n    return isInstanceOf(value, 'Identity', Identity)\n  }\n\n  /**\n   * The system-facing identifier for this participant — never sent to the model directly.\n   */\n  declare readonly identifier: string | number\n\n  /**\n   * How this participant is presented to the model, as a {@link @nhtio/adk!Tokenizable} for inline\n   * token estimation.\n   */\n  declare readonly representation: Tokenizable\n\n  #identifier: string | number\n  #representation: Tokenizable\n\n  /**\n   * @param raw - The raw identity input validated against `rawIdentitySchema`.\n   * @throws {@link @nhtio/adk!E_INVALID_INITIAL_IDENTITY_VALUE} when `raw` does not satisfy the schema.\n   */\n  constructor(raw: RawIdentity) {\n    let resolved: ResolvedIdentity\n    try {\n      resolved = validateOrThrow<ResolvedIdentity>(rawIdentitySchema, raw, true)\n    } catch (err) {\n      throw new E_INVALID_INITIAL_IDENTITY_VALUE({ cause: isError(err) ? err : undefined })\n    }\n    this.#identifier = resolved.identifier\n    this.#representation = Tokenizable.isTokenizable(resolved.representation)\n      ? resolved.representation\n      : new Tokenizable(resolved.representation)\n\n    Object.defineProperties(this, {\n      identifier: {\n        get: () => this.#identifier,\n        enumerable: true,\n        configurable: false,\n      },\n      representation: {\n        get: () => this.#representation,\n        enumerable: true,\n        configurable: false,\n      },\n    })\n  }\n}\n","import { Tokenizable } from './tokenizable'\nimport { validator } from '@nhtio/validation'\nimport { validateOrThrow } from '../utils/validation'\nimport { isInstanceOf, isError } from '../utils/guards'\nimport { E_INVALID_INITIAL_MEMORY_VALUE } from '../exceptions/runtime'\nimport type { DateTime } from 'luxon'\n\n/**\n * Plain input object supplied to {@link Memory} at construction time.\n *\n * @remarks\n * Validated against `rawMemorySchema` before the `Memory` instance is created.\n * Temporal fields accept any value that Luxon can parse — ISO strings, Unix timestamps,\n * `Date` objects, or existing `DateTime` instances.\n */\nexport interface RawMemory {\n  /** Stable unique identifier for this memory entry. */\n  id: string\n  /** The memory content as a plain string or an existing {@link @nhtio/adk!Tokenizable} instance. */\n  content: string | Tokenizable\n  /** Confidence score in the range `[0, 1]` — how certain the agent is that this memory is accurate. */\n  confidence: number\n  /** Importance score in the range `[0, 1]` — how much weight this memory should carry during retrieval. */\n  importance: number\n  /** When this memory was first recorded. */\n  createdAt: string | number | Date | DateTime\n  /** When this memory was last modified. */\n  updatedAt: string | number | Date | DateTime\n}\n\n/**\n * A fully-resolved {@link RawMemory} where all fields have been validated and temporal values\n * normalised to Luxon `DateTime` instances.\n *\n * @remarks\n * This is the shape returned by `rawMemorySchema` after validation — used internally by the\n * {@link Memory} constructor to assign private fields with guaranteed types.\n */\ninterface ResolvedMemory {\n  id: string\n  content: Tokenizable\n  confidence: number\n  importance: number\n  createdAt: DateTime\n  updatedAt: DateTime\n}\n\n/**\n * Validator schema used to validate a {@link RawMemory} before constructing a {@link Memory}.\n *\n * @remarks\n * Validates all six fields of {@link RawMemory}:\n * - `id` — required non-empty string.\n * - `content` — required string or {@link @nhtio/adk!Tokenizable}, via {@link @nhtio/adk!Tokenizable.schema}.\n * - `confidence` — required number in `[0, 1]`.\n * - `importance` — required number in `[0, 1]`.\n * - `createdAt` / `updatedAt` — required datetime-parseable values, normalised to `DateTime`.\n *\n * Throws {@link @nhtio/adk!E_INVALID_INITIAL_MEMORY_VALUE} (via the {@link Memory} constructor) when\n * validation fails.\n */\nconst rawMemorySchema = validator.object<RawMemory>({\n  id: validator.string().required(),\n  content: Tokenizable.schema.required(),\n  confidence: validator.number().min(0).max(1).required(),\n  importance: validator.number().min(0).max(1).required(),\n  createdAt: validator.datetime().required(),\n  updatedAt: validator.datetime().required(),\n})\n\n/**\n * An immutable, validated memory entry held by the agent.\n *\n * @remarks\n * Constructed from a {@link RawMemory} via `rawMemorySchema`. All temporal fields are\n * normalised to Luxon `DateTime` instances at construction time. The `content` field is\n * always a {@link @nhtio/adk!Tokenizable} so callers can estimate token cost without an additional\n * wrapping step.\n */\nexport class Memory {\n  /**\n   * Validator schema that accepts a {@link RawMemory} object.\n   *\n   * @remarks\n   * Reusable fragment for any schema that needs to validate or nest a memory entry — for\n   * example, a collection schema that holds an array of memories.\n   */\n  public static schema = rawMemorySchema\n\n  /**\n   * Returns `true` if `value` is a {@link Memory} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety — `instanceof` would fail for instances\n   * created in a different module copy or VM context.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is a {@link Memory} instance.\n   */\n  public static isMemory(value: unknown): value is Memory {\n    return isInstanceOf(value, 'Memory', Memory)\n  }\n  /** Stable unique identifier for this memory entry. */\n  declare readonly id: string\n  /** The memory content as a {@link @nhtio/adk!Tokenizable} for inline token estimation. */\n  declare readonly content: Tokenizable\n  /** Confidence score in the range `[0, 1]`. */\n  declare readonly confidence: number\n  /** Importance score in the range `[0, 1]`. */\n  declare readonly importance: number\n  /** When this memory was first recorded. */\n  declare readonly createdAt: DateTime\n  /** When this memory was last modified. */\n  declare readonly updatedAt: DateTime\n\n  #id: string\n  #content: Tokenizable\n  #confidence: number\n  #importance: number\n  #createdAt: DateTime\n  #updatedAt: DateTime\n\n  /**\n   * @param raw - The raw memory input validated against `rawMemorySchema`.\n   * @throws {@link @nhtio/adk!E_INVALID_INITIAL_MEMORY_VALUE} when `raw` does not satisfy the schema.\n   */\n  constructor(raw: RawMemory) {\n    let resolved: ResolvedMemory\n    try {\n      resolved = validateOrThrow<ResolvedMemory>(rawMemorySchema, raw, true)\n    } catch (err) {\n      throw new E_INVALID_INITIAL_MEMORY_VALUE({ cause: isError(err) ? err : undefined })\n    }\n    this.#id = resolved.id\n    this.#content = Tokenizable.isTokenizable(resolved.content)\n      ? resolved.content\n      : new Tokenizable(resolved.content)\n    this.#confidence = resolved.confidence\n    this.#importance = resolved.importance\n    this.#createdAt = resolved.createdAt\n    this.#updatedAt = resolved.updatedAt\n\n    Object.defineProperties(this, {\n      id: {\n        get: () => this.#id,\n        enumerable: true,\n        configurable: false,\n      },\n      content: {\n        get: () => this.#content,\n        enumerable: true,\n        configurable: false,\n      },\n      confidence: {\n        get: () => this.#confidence,\n        enumerable: true,\n        configurable: false,\n      },\n      importance: {\n        get: () => this.#importance,\n        enumerable: true,\n        configurable: false,\n      },\n      createdAt: {\n        get: () => this.#createdAt,\n        enumerable: true,\n        configurable: false,\n      },\n      updatedAt: {\n        get: () => this.#updatedAt,\n        enumerable: true,\n        configurable: false,\n      },\n    })\n  }\n}\n","import { Media } from './media'\nimport { Identity } from './identity'\nimport { Tokenizable } from './tokenizable'\nimport { validator } from '@nhtio/validation'\nimport { validateOrThrow } from '../utils/validation'\nimport { isInstanceOf, isError } from '../utils/guards'\nimport { E_INVALID_INITIAL_MESSAGE_VALUE } from '../exceptions/runtime'\nimport type { DateTime } from 'luxon'\nimport type { RawIdentity } from './identity'\n\n/**\n * The roles a {@link Message} author can hold.\n *\n * @remarks\n * Restricted to `user` and `assistant` — system instructions, developer directives, and\n * tool results are handled separately and never appear in the persisted message history.\n */\nexport type MessageRole = 'user' | 'assistant'\n\n/**\n * Plain input object supplied to {@link Message} at construction time.\n *\n * @remarks\n * Validated against `rawMessageSchema` before the `Message` instance is created.\n * Temporal fields accept any value that Luxon can parse — ISO strings, Unix timestamps,\n * `Date` objects, or existing `DateTime` instances.\n *\n * At least one of `content` or `attachments` (non-empty) must be present — a message with\n * neither throws {@link @nhtio/adk!E_INVALID_INITIAL_MESSAGE_VALUE}.\n */\nexport interface RawMessage {\n  /** Stable unique identifier for this message. */\n  id: string\n  /** Whether this message is from the human participant or the model. */\n  role: MessageRole\n  /**\n   * The message content as a plain string or an existing {@link @nhtio/adk!Tokenizable} instance.\n   *\n   * @remarks\n   * Optional — but required when `attachments` is absent or empty. The cross-field rule on\n   * `rawMessageSchema` enforces that at least one of `content` or `attachments` is present.\n   */\n  content?: string | Tokenizable\n  /**\n   * Media attachments carried by this message — images, audio, video, documents.\n   *\n   * @remarks\n   * Optional and symmetric across roles: both `user` and `assistant` messages may carry\n   * attachments. Each attachment carries its own `trustTier` and `modalityHazard`, which the\n   * renderer uses to wrap the asset in its own trust envelope independent of the message\n   * envelope. How a renderer orders text vs attachments in the on-the-wire content array is\n   * a renderer-policy concern, not a contract of {@link Message}.\n   */\n  attachments?: Media[]\n  /**\n   * The identity of the participant who authored this message.\n   *\n   * @remarks\n   * Optional. When omitted, the `role` value is used as both the system-facing `identifier`\n   * and the model-facing `representation`. Three accepted forms when provided:\n   * - A plain `string` — used as both `identifier` and `representation`.\n   * - A {@link @nhtio/adk!RawIdentity} object — validated and wrapped into an {@link @nhtio/adk!Identity}.\n   * - An existing {@link @nhtio/adk!Identity} instance — passed through unchanged.\n   */\n  identity?: string | RawIdentity | Identity\n  /** When this message was created. */\n  createdAt: string | number | Date | DateTime\n  /** When this message was last modified. */\n  updatedAt: string | number | Date | DateTime\n}\n\n/**\n * A fully-resolved {@link RawMessage} where temporal fields have been normalised to Luxon\n * `DateTime` instances and `identity` is a validated {@link @nhtio/adk!Identity}.\n *\n * @remarks\n * Used internally by the {@link Message} constructor to assign private fields with\n * guaranteed types.\n */\ninterface ResolvedMessage {\n  id: string\n  role: MessageRole\n  content?: Tokenizable\n  attachments: Media[]\n  identity: string | RawIdentity | Identity\n  createdAt: DateTime\n  updatedAt: DateTime\n}\n\n/**\n * Validator schema used to validate a {@link RawMessage} before constructing a {@link Message}.\n *\n * @remarks\n * Validates all fields of {@link RawMessage}:\n * - `id` — required non-empty string.\n * - `role` — required; must be `'user'` or `'assistant'`.\n * - `content` — optional string or {@link @nhtio/adk!Tokenizable}, via {@link @nhtio/adk!Tokenizable.schema}.\n * - `attachments` — optional array of {@link @nhtio/adk!Media} instances. Defaults to `[]`.\n * - At least one of `content` or `attachments` must be present and non-empty; a message with\n *   neither is invalid.\n * - `identity` — required string, {@link @nhtio/adk!RawIdentity}, or {@link @nhtio/adk!Identity}; a plain string is\n *   mapped to both `identifier` and `representation` automatically.\n * - `createdAt` / `updatedAt` — required datetime-parseable values, normalised to `DateTime`.\n *\n * Throws {@link @nhtio/adk!E_INVALID_INITIAL_MESSAGE_VALUE} (via the {@link Message} constructor) when\n * validation fails.\n */\nconst rawMessageSchema = validator\n  .object<RawMessage>({\n    id: validator.string().required(),\n    role: validator.string().valid('user', 'assistant').required(),\n    content: Tokenizable.schema.optional(),\n    attachments: validator\n      .array()\n      .items(\n        validator.any().custom((value, helpers) => {\n          if (Media.isMedia(value)) return value\n          return helpers.error('any.invalid')\n        })\n      )\n      .default([]),\n    identity: validator\n      .alternatives(validator.string(), Identity.schema)\n      .default(validator.ref('role')),\n    createdAt: validator.datetime().required(),\n    updatedAt: validator.datetime().required(),\n  })\n  .custom((value, helpers) => {\n    const resolved = value as ResolvedMessage\n    const hasContent = resolved.content !== undefined && resolved.content !== null\n    const hasAttachments = Array.isArray(resolved.attachments) && resolved.attachments.length > 0\n    if (!hasContent && !hasAttachments) {\n      return helpers.error('any.invalid')\n    }\n    return resolved\n  })\n\n/**\n * An immutable, validated conversation message from a human participant or the model.\n *\n * @remarks\n * Covers only `user` and `assistant` roles — system instructions, developer directives, and\n * tool results are not represented here. Constructed from a {@link RawMessage} via\n * `rawMessageSchema`. Temporal fields are normalised to Luxon `DateTime` instances at\n * construction time. Both `content` and `identity.representation` are {@link @nhtio/adk!Tokenizable} so\n * token cost can be estimated inline.\n *\n * A message may carry `content` (text), `attachments` (media), or both. The cross-field rule\n * on `rawMessageSchema` enforces that at least one is present. Downstream code that reaches\n * for `message.content` must handle the attachments-only case where `content` is `undefined`.\n */\nexport class Message {\n  /**\n   * Validator schema that accepts a {@link RawMessage} object.\n   *\n   * @remarks\n   * Reusable fragment for any schema that needs to validate or nest a message entry — for\n   * example, a collection schema that holds an array of messages.\n   */\n  public static schema = rawMessageSchema\n\n  /**\n   * Returns `true` if `value` is a {@link Message} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety — `instanceof` would fail for instances\n   * created in a different module copy or VM context.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is a {@link Message} instance.\n   */\n  public static isMessage(value: unknown): value is Message {\n    return isInstanceOf(value, 'Message', Message)\n  }\n\n  /** Stable unique identifier for this message. */\n  declare readonly id: string\n  /** Whether this message is from the human participant or the model. */\n  declare readonly role: MessageRole\n  /**\n   * The message content as a {@link @nhtio/adk!Tokenizable} for inline token estimation, or `undefined`\n   * for attachments-only messages.\n   *\n   * @remarks\n   * `undefined` when the message was constructed with only `attachments`. Render code that\n   * needs the text portion must guard for the missing case rather than blindly calling\n   * `message.content.toString()`.\n   */\n  declare readonly content: Tokenizable | undefined\n  /**\n   * Media attachments carried by this message.\n   *\n   * @remarks\n   * Always defined as a frozen array — empty when the message has no attachments. Both\n   * `user` and `assistant` messages may carry attachments. Each entry carries its own\n   * `trustTier` and `modalityHazard`; the renderer wraps each in its own trust envelope\n   * independent of the message envelope.\n   */\n  declare readonly attachments: ReadonlyArray<Media>\n  /** The identity of the participant who authored this message. */\n  declare readonly identity: Identity\n  /** When this message was created. */\n  declare readonly createdAt: DateTime\n  /** When this message was last modified. */\n  declare readonly updatedAt: DateTime\n\n  #id: string\n  #role: MessageRole\n  #content: Tokenizable | undefined\n  #attachments: ReadonlyArray<Media>\n  #identity: Identity\n  #createdAt: DateTime\n  #updatedAt: DateTime\n\n  /**\n   * @param raw - The raw message input validated against `rawMessageSchema`.\n   * @throws {@link @nhtio/adk!E_INVALID_INITIAL_MESSAGE_VALUE} when `raw` does not satisfy the schema —\n   *   including the cross-field rule that at least one of `content` or `attachments` must be\n   *   present and non-empty.\n   */\n  constructor(raw: RawMessage) {\n    let resolved: ResolvedMessage\n    try {\n      resolved = validateOrThrow<ResolvedMessage>(rawMessageSchema, raw, true)\n    } catch (err) {\n      throw new E_INVALID_INITIAL_MESSAGE_VALUE({ cause: isError(err) ? err : undefined })\n    }\n    this.#id = resolved.id\n    this.#role = resolved.role\n    this.#content =\n      resolved.content === undefined || resolved.content === null\n        ? undefined\n        : Tokenizable.isTokenizable(resolved.content)\n          ? resolved.content\n          : new Tokenizable(resolved.content)\n    this.#attachments = Object.freeze([...(resolved.attachments ?? [])])\n    const rawIdentity = resolved.identity\n    this.#identity = Identity.isIdentity(rawIdentity)\n      ? rawIdentity\n      : typeof rawIdentity === 'string'\n        ? new Identity({ identifier: rawIdentity, representation: rawIdentity })\n        : new Identity(rawIdentity)\n    this.#createdAt = resolved.createdAt\n    this.#updatedAt = resolved.updatedAt\n\n    Object.defineProperties(this, {\n      id: {\n        get: () => this.#id,\n        enumerable: true,\n        configurable: false,\n      },\n      role: {\n        get: () => this.#role,\n        enumerable: true,\n        configurable: false,\n      },\n      content: {\n        get: () => this.#content,\n        enumerable: true,\n        configurable: false,\n      },\n      attachments: {\n        get: () => this.#attachments,\n        enumerable: true,\n        configurable: false,\n      },\n      identity: {\n        get: () => this.#identity,\n        enumerable: true,\n        configurable: false,\n      },\n      createdAt: {\n        get: () => this.#createdAt,\n        enumerable: true,\n        configurable: false,\n      },\n      updatedAt: {\n        get: () => this.#updatedAt,\n        enumerable: true,\n        configurable: false,\n      },\n    })\n  }\n}\n","import { Identity } from './identity'\nimport { Tokenizable } from './tokenizable'\nimport { validator } from '@nhtio/validation'\nimport { validateOrThrow } from '../utils/validation'\nimport { isInstanceOf, isError } from '../utils/guards'\nimport { E_INVALID_INITIAL_THOUGHT_VALUE } from '../exceptions/runtime'\nimport type { DateTime } from 'luxon'\nimport type { RawIdentity } from './identity'\n\n/**\n * Plain input object supplied to {@link Thought} at construction time.\n *\n * @remarks\n * Validated against `rawThoughtSchema` before the `Thought` instance is created.\n * Temporal fields accept any value that Luxon can parse — ISO strings, Unix timestamps,\n * `Date` objects, or existing `DateTime` instances.\n */\nexport interface RawThought {\n  /** Stable unique identifier for this thought. */\n  id: string\n  /** The reasoning content as a plain string or an existing {@link @nhtio/adk!Tokenizable} instance. */\n  content: string | Tokenizable\n  /**\n   * The identity of the agent who produced this thought.\n   *\n   * @remarks\n   * Required in multi-agent conversations to attribute reasoning traces to a specific agent.\n   * Three accepted forms when provided:\n   * - A plain `string` — used as both `identifier` and `representation`.\n   * - A {@link @nhtio/adk!RawIdentity} object — validated and wrapped into an {@link @nhtio/adk!Identity}.\n   * - An existing {@link @nhtio/adk!Identity} instance — passed through unchanged.\n   *\n   * When omitted, defaults to `'assistant'` (both `identifier` and `representation`).\n   */\n  identity?: string | RawIdentity | Identity\n  /**\n   * Optional vendor-opaque payload that round-trips back to a matching model wire.\n   *\n   * @remarks\n   * Carries anything the ADK cannot interpret but a specific provider can — for example,\n   * an Anthropic Messages thinking-block `signature`, an OpenAI Responses\n   * `ResponseReasoningItem.encrypted_content` blob, a DeepSeek server-side reasoning handle,\n   * or an MCP-mediated reasoning item.\n   *\n   * When present, an LLM battery MUST treat the thought as **opaque-mode**: do NOT inline\n   * `content` through the plain `<thought>` envelope; serialise `payload` back to the wire in\n   * whichever shape the matching {@link RawThought.replayCompatibility} identifier specifies.\n   * The plain-text `content` is kept alongside for token-accounting and human/observer\n   * inspection — it is not the thing the model sees.\n   *\n   * Cross-field invariant: a present `payload` REQUIRES a present {@link RawThought.replayCompatibility}.\n   * A `payload` without `replayCompatibility` is malformed (the ADK has no way to know\n   * which adapter can consume it) and {@link Thought.schema} rejects with\n   * {@link @nhtio/adk!E_INVALID_INITIAL_THOUGHT_VALUE}.\n   *\n   * @defaultValue `undefined`\n   */\n  payload?: unknown\n  /**\n   * Optional free-form identifier describing which adapter wire-shape this thought can be\n   * safely replayed into.\n   *\n   * @remarks\n   * Examples (none of these are reserved by the ADK — they are consumer conventions):\n   *   - `'plain-text'` — replayable into every LLM battery\n   *   - `'anthropic-messages-thinking-v1'`\n   *   - `'openai-responses-reasoning-item-v1'`\n   *   - `'deepseek-reasoning-handle-v1'`\n   *\n   * LLM batteries declare via constructor option which tags they can safely replay; matching\n   * opaque thoughts are routed to the wire's typed reasoning channel where it exists, or to a\n   * documented side-channel key on the request body where the wire has none. Non-matching\n   * opaque thoughts are elided from the current dispatch but NOT removed from\n   * `ctx.turnThoughts` — they remain in context so a subsequent dispatch to a different\n   * adapter that DOES declare the matching tag can pick them up.\n   *\n   * Plain-text thoughts (`payload === undefined` AND `replayCompatibility === undefined`, or\n   * explicit `replayCompatibility: 'plain-text'`) are always replayable.\n   *\n   * A `replayCompatibility` without a `payload` is allowed — it documents intent (\"this\n   * plain-text thought is only meaningful to a specific fine-tuned variant\") without\n   * requiring an opaque blob.\n   *\n   * @defaultValue `undefined`\n   */\n  replayCompatibility?: string\n  /** When this thought was recorded. */\n  createdAt: string | number | Date | DateTime\n  /** When this thought was last modified. */\n  updatedAt: string | number | Date | DateTime\n}\n\n/**\n * A fully-resolved {@link RawThought} where temporal fields have been normalised to Luxon\n * `DateTime` instances.\n *\n * @remarks\n * Used internally by the {@link Thought} constructor to assign private fields with\n * guaranteed types.\n */\ninterface ResolvedThought {\n  id: string\n  content: Tokenizable\n  identity: string | RawIdentity | Identity\n  payload?: unknown\n  replayCompatibility?: string\n  createdAt: DateTime\n  updatedAt: DateTime\n}\n\n/**\n * Validator schema used to validate a {@link RawThought} before constructing a {@link Thought}.\n *\n * @remarks\n * Validates all fields of {@link RawThought}:\n * - `id` — required non-empty string.\n * - `content` — required string or {@link @nhtio/adk!Tokenizable}, via {@link @nhtio/adk!Tokenizable.schema}.\n * - `identity` — optional string, {@link @nhtio/adk!RawIdentity}, or {@link @nhtio/adk!Identity}; defaults to\n *   `'assistant'` when omitted.\n * - `createdAt` / `updatedAt` — required datetime-parseable values, normalised to `DateTime`.\n *\n * Throws {@link @nhtio/adk!E_INVALID_INITIAL_THOUGHT_VALUE} (via the {@link Thought} constructor) when\n * validation fails.\n */\nconst rawThoughtSchema = validator\n  .object<RawThought>({\n    id: validator.string().required(),\n    content: Tokenizable.schema.required(),\n    identity: validator.alternatives(validator.string(), Identity.schema).default('assistant'),\n    payload: validator.any().optional(),\n    replayCompatibility: validator.string().min(1).optional(),\n    createdAt: validator.datetime().required(),\n    updatedAt: validator.datetime().required(),\n  })\n  .custom((value, helpers) => {\n    const v = value as RawThought\n    if (\n      v.payload !== undefined &&\n      (v.replayCompatibility === undefined || v.replayCompatibility === null)\n    ) {\n      return helpers.error('any.invalid')\n    }\n    return value\n  })\n\n/**\n * An immutable, validated internal reasoning trace produced by an agent.\n *\n * @remarks\n * Represents an agent's internal thinking — distinct from {@link @nhtio/adk!Message} (which is part of\n * the visible conversation) and never shown to end users directly. Carries an `identity` so\n * reasoning traces can be attributed to a specific agent in multi-agent conversations.\n * Constructed from a {@link RawThought} via `rawThoughtSchema`. The `content` field is always\n * a {@link @nhtio/adk!Tokenizable} so token cost can be estimated inline.\n */\nexport class Thought {\n  /**\n   * Validator schema that accepts a {@link RawThought} object.\n   *\n   * @remarks\n   * Reusable fragment for any schema that needs to validate or nest a thought entry.\n   */\n  public static schema = rawThoughtSchema\n\n  /**\n   * Returns `true` if `value` is a {@link Thought} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety — `instanceof` would fail for instances\n   * created in a different module copy or VM context.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is a {@link Thought} instance.\n   */\n  public static isThought(value: unknown): value is Thought {\n    return isInstanceOf(value, 'Thought', Thought)\n  }\n\n  /** Stable unique identifier for this thought. */\n  declare readonly id: string\n  /** The reasoning content as a {@link @nhtio/adk!Tokenizable} for inline token estimation. */\n  declare readonly content: Tokenizable\n  /** The identity of the agent who produced this thought. */\n  declare readonly identity: Identity\n  /**\n   * Optional vendor-opaque payload that round-trips back to a matching model wire.\n   * See {@link RawThought.payload}.\n   */\n  declare readonly payload: unknown\n  /**\n   * Optional wire-shape identifier describing which adapter can safely replay this thought.\n   * See {@link RawThought.replayCompatibility}.\n   */\n  declare readonly replayCompatibility: string | undefined\n  /** When this thought was recorded. */\n  declare readonly createdAt: DateTime\n  /** When this thought was last modified. */\n  declare readonly updatedAt: DateTime\n\n  #id: string\n  #content: Tokenizable\n  #identity: Identity\n  #payload: unknown\n  #replayCompatibility: string | undefined\n  #createdAt: DateTime\n  #updatedAt: DateTime\n\n  /**\n   * @param raw - The raw thought input validated against `rawThoughtSchema`.\n   * @throws {@link @nhtio/adk!E_INVALID_INITIAL_THOUGHT_VALUE} when `raw` does not satisfy the schema.\n   */\n  constructor(raw: RawThought) {\n    let resolved: ResolvedThought\n    try {\n      resolved = validateOrThrow<ResolvedThought>(rawThoughtSchema, raw, true)\n    } catch (err) {\n      throw new E_INVALID_INITIAL_THOUGHT_VALUE({ cause: isError(err) ? err : undefined })\n    }\n    this.#id = resolved.id\n    this.#content = Tokenizable.isTokenizable(resolved.content)\n      ? resolved.content\n      : new Tokenizable(resolved.content)\n    const rawIdentity = resolved.identity\n    this.#identity = Identity.isIdentity(rawIdentity)\n      ? rawIdentity\n      : typeof rawIdentity === 'string'\n        ? new Identity({ identifier: rawIdentity, representation: rawIdentity })\n        : new Identity(rawIdentity)\n    this.#payload = resolved.payload\n    this.#replayCompatibility = resolved.replayCompatibility\n    this.#createdAt = resolved.createdAt\n    this.#updatedAt = resolved.updatedAt\n\n    Object.defineProperties(this, {\n      id: {\n        get: () => this.#id,\n        enumerable: true,\n        configurable: false,\n      },\n      content: {\n        get: () => this.#content,\n        enumerable: true,\n        configurable: false,\n      },\n      identity: {\n        get: () => this.#identity,\n        enumerable: true,\n        configurable: false,\n      },\n      payload: {\n        get: () => this.#payload,\n        enumerable: true,\n        configurable: false,\n      },\n      replayCompatibility: {\n        get: () => this.#replayCompatibility,\n        enumerable: true,\n        configurable: false,\n      },\n      createdAt: {\n        get: () => this.#createdAt,\n        enumerable: true,\n        configurable: false,\n      },\n      updatedAt: {\n        get: () => this.#updatedAt,\n        enumerable: true,\n        configurable: false,\n      },\n    })\n  }\n}\n"],"mappings":"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"}

package/{tool-CsYuHhiS.mjs → tool-CRZSUcdP.mjs}

@@ -1,6 +1,6 @@
 import { a as validateOrThrow, i as passesSchema, n as ValidationException, r as asyncValidateOrThrow } from "./exceptions-BeWH2FwP.mjs";
-import { n as canonicalStringify, o as isError, r as Registry, s as isInstanceOf } from "./tool_registry-CX3ofUh9.mjs";
-import { D as E_TOOL_DOWNSTREAM_ERROR, d as E_INVALID_INITIAL_TOOL_VALUE, h as E_INVALID_TOOL_ARGS } from "./runtime-CDIZwCT0.mjs";
+import { n as canonicalStringify, o as isError, r as Registry, s as isInstanceOf } from "./tool_registry-BGHg6KTq.mjs";
+import { D as E_TOOL_DOWNSTREAM_ERROR, d as E_INVALID_INITIAL_TOOL_VALUE, h as E_INVALID_TOOL_ARGS } from "./runtime-j92CNi5z.mjs";
 import { validator } from "@nhtio/validation";
 import { DateTime } from "luxon";
 import { sha256 } from "js-sha256";
@@ -293,4 +293,4 @@ var Tool = class Tool {
 //#endregion
 export { Tool as t };
 
-//# sourceMappingURL=tool-CsYuHhiS.mjs.map
+//# sourceMappingURL=tool-CRZSUcdP.mjs.map

package/{tool-CsYuHhiS.mjs.map → tool-CRZSUcdP.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"tool-CsYuHhiS.mjs","names":["#name","#description","#inputSchema","#handler","#artifactConstructor","#meta","#ephemeral","#trusted","#onCollision"],"sources":["../src/lib/contracts/spooled_artifact_constructor.ts","../src/lib/classes/tool.ts"],"sourcesContent":["import { validator } from '@nhtio/validation'\nimport { passesSchema } from '../utils/validation'\nimport type { SpooledArtifact } from '../classes/spooled_artifact'\n\n/**\n * Constructor signature for any {@link @nhtio/adk!SpooledArtifact} (the class itself or a subclass).\n *\n * @remarks\n * Re-declared here at the contract level so consumers — and the `Tool.artifactConstructor`\n * resolver validator in particular — can talk about the constructor shape without value-importing\n * the {@link @nhtio/adk!SpooledArtifact} class (which would close the `tool.ts` ↔ `spooled_artifact.ts` ↔\n * `artifact_tool.ts` module cycle at load time and TDZ-crash `ArtifactTool extends Tool`).\n *\n * @typeParam A - The {@link @nhtio/adk!SpooledArtifact} subtype the constructor produces.\n */\nexport type SpooledArtifactConstructorLike<A extends SpooledArtifact = SpooledArtifact> = new (\n  ...args: any[]\n) => A\n\nconst ARTIFACT_METHODS = [\n  'head',\n  'tail',\n  'grep',\n  'cat',\n  'byteLength',\n  'lineCount',\n  'estimateTokens',\n] as const\n\n/**\n * Validator schema used to validate a {@link SpooledArtifactConstructorLike} value.\n *\n * @remarks\n * Because the validator is invoked at validate-time (not at module-load), it is safe to inspect\n * the constructor's prototype here. The check is duck-typed: the value must be a function whose\n * `prototype` carries every canonical artifact instance method (`head`, `tail`, `grep`, `cat`,\n * `byteLength`, `lineCount`, `estimateTokens`). This mirrors {@link spoolReaderSchema}'s\n * cross-realm-safe duck-type pattern — `instanceof SpooledArtifact` would be tighter but would\n * force a value-import of the class and reopen the module cycle.\n */\nexport const spooledArtifactConstructorSchema = validator.any().custom((value, helpers) => {\n  if (typeof value !== 'function') return helpers.error('any.invalid')\n  const proto = (value as { prototype?: unknown }).prototype\n  if (proto === undefined || proto === null) return helpers.error('any.invalid')\n  if (ARTIFACT_METHODS.every((m) => typeof (proto as Record<string, unknown>)[m] === 'function')) {\n    return value\n  }\n  return helpers.error('any.invalid')\n})\n\n/**\n * Returns `true` if `value` is a constructor whose prototype carries every canonical\n * {@link @nhtio/adk!SpooledArtifact} instance method.\n *\n * @remarks\n * Duck-typed; does not use `instanceof SpooledArtifact`. Used by the `Tool.artifactConstructor`\n * resolver validator and any other site that needs to recognise a `SpooledArtifact`-like\n * constructor without pulling the class into its module-load graph.\n *\n * @param value - The value to test.\n * @returns `true` when `value` is a `SpooledArtifact`-shaped constructor.\n */\nexport const implementsSpooledArtifactConstructor = (\n  value: unknown\n): value is SpooledArtifactConstructorLike => {\n  return passesSchema(spooledArtifactConstructorSchema, value)\n}\n","import { DateTime } from 'luxon'\nimport { sha256 } from 'js-sha256'\nimport { Registry } from './registry'\nimport { validator } from '@nhtio/validation'\nimport { isInstanceOf, isError } from '../utils/guards'\nimport { canonicalStringify } from '../utils/canonical_json'\nimport { validateOrThrow, asyncValidateOrThrow, ValidationException } from '../utils/validation'\nimport { implementsSpooledArtifactConstructor } from '../contracts/spooled_artifact_constructor'\nimport {\n  E_INVALID_INITIAL_TOOL_VALUE,\n  E_INVALID_TOOL_ARGS,\n  E_TOOL_DOWNSTREAM_ERROR,\n} from '../exceptions/runtime'\nimport type { Media } from './media'\nimport type { Schema, Description } from '@nhtio/validation'\nimport type { DispatchContext } from '../contracts/dispatch_context'\nimport type { SpooledArtifact, SpooledArtifactConstructor } from './spooled_artifact'\n\n/**\n * A zero-arg function that returns the {@link @nhtio/adk!SpooledArtifactConstructor} the consumer should\n * use when wrapping this tool's serialised output into a `ToolCall.results` field.\n *\n * @remarks\n * Why a resolver (and not the constructor itself)? `tool.ts` participates in a module-load\n * cycle with `spooled_artifact.ts` and `artifact_tool.ts` (`ArtifactTool extends Tool` closes\n * the loop). Any eager value-level reference to `SpooledArtifact` in `tool.ts` would crash the\n * cycle with a TDZ error. A resolver lets `tool.ts` validate \"is a function\" at module-load\n * time and defer the actual constructor check to validate-time (which always runs after every\n * module body has executed). Wrap-sites invoke `tool.artifactConstructor?.() ?? SpooledArtifact`\n * to obtain the final constructor.\n */\nexport type ArtifactConstructorResolver<A extends SpooledArtifact = SpooledArtifact> =\n  () => SpooledArtifactConstructor<A>\n\n/**\n * The execution function for a {@link Tool}.\n *\n * @remarks\n * Receives the raw arguments passed to the executor, the active {@link @nhtio/adk!DispatchContext}, and the\n * tool's metadata registry.\n *\n * Return shapes:\n * - `string` / `Uint8Array` — opaque serialised output. The ADK does not persist the bytes\n *   itself; the consumer's executor middleware is responsible for storing them and wrapping\n *   them via `tool.artifactConstructor?.() ?? SpooledArtifact` when assembling the `ToolCall`\n *   record.\n * - {@link @nhtio/adk!Media} / `Media[]` — explicit-modality silo. Bypasses\n *   {@link Tool.artifactConstructor} — the handler returns the final result shape directly.\n *   The LLM battery renders each `Media` as a provider-specific content block.\n */\nexport type ToolHandler = (\n  args: unknown,\n  ctx: DispatchContext,\n  meta: Registry\n) => string | Uint8Array | Media | Media[] | Promise<string | Uint8Array | Media | Media[]>\n\n/**\n * Plain input object supplied to {@link Tool} at construction time.\n *\n * @typeParam A - The {@link @nhtio/adk!SpooledArtifact} subtype used to wrap this tool's results when\n *   the consumer assembles a `ToolCall.results` field. Defaults to {@link @nhtio/adk!SpooledArtifact}\n *   (plain text). Tools producing JSON output should set this to `SpooledJsonArtifact`; tools\n *   producing markdown should set it to `SpooledMarkdownArtifact`; consumers can also pass a\n *   custom subclass.\n */\nexport interface RawTool<A extends SpooledArtifact = SpooledArtifact> {\n  /** Unique identifier used in LLM tool definitions. Recommend lowercase snake_case. */\n  name: string\n  /** Human-readable description passed to the model to explain what the tool does. */\n  description: string\n  /** @nhtio/validation schema for the tool's input arguments. Annotate with `.description()`, `.note()`, `.example()` etc. to produce rich LLM tool definitions via `.describe()`. */\n  inputSchema: Schema\n  /** Execution function. Not exposed as a public property — invoke via `executor()`. */\n  handler: ToolHandler\n  /**\n   * Zero-arg resolver returning the {@link @nhtio/adk!SpooledArtifactConstructor} the consumer should use\n   * when wrapping this tool's serialised output into a `ToolCall.results` field. Optional —\n   * when omitted, wrap-sites fall back to {@link @nhtio/adk!SpooledArtifact} (plain text).\n   *\n   * @remarks\n   * Recommended call shape: `artifactConstructor: () => SpooledJsonArtifact`. The closure is\n   * the indirection that lets `tool.ts` validate this field without eagerly importing\n   * `SpooledArtifact` (which would crash the `tool.ts ↔ spooled_artifact.ts ↔ artifact_tool.ts`\n   * module-load cycle). At validate time the schema invokes the resolver and verifies its\n   * return value is a `SpooledArtifact`-derived constructor — wrong-shape resolvers throw\n   * {@link @nhtio/adk!E_INVALID_INITIAL_TOOL_VALUE}.\n   *\n   * Wrap-sites (storage batteries, scripted executors) read the constructor via\n   * `tool.artifactConstructor?.() ?? SpooledArtifact`.\n   */\n  artifactConstructor?: ArtifactConstructorResolver<A>\n  /** 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. */\n  meta?: Record<string, unknown>\n  /**\n   * When `true`, marks this tool as owned by a specific {@link @nhtio/adk!DispatchContext} so that\n   * `ToolRegistry.pruneEphemeral()` will drop it at ctx-completion.\n   *\n   * @remarks\n   * The flag is advisory at the `Tool` level — registries decide what to do with it. The canonical\n   * producer of ephemeral tools is `SpooledArtifact.forgeTools(ctx)`, which sets this to `true`\n   * on every artifact-query tool it emits.\n   *\n   * @defaultValue `false`\n   */\n  ephemeral?: boolean\n  /**\n   * When `true`, declares that this tool's output should be treated as **trusted developer/user\n   * intent** rather than as untrusted third-party text when surfaced to the model.\n   *\n   * @remarks\n   * LLM batteries read this flag per call when rendering tool-call results. The default\n   * untrusted envelope (e.g. `<untrusted_content>` in the OpenAI Chat Completions battery) is the\n   * secure-by-default treatment for arbitrary tool output. A tool whose output is authored by the\n   * user or operator (Q&A tools surfacing user-authored answers, human-in-the-loop approval\n   * gates, feedback-collection tools, configuration tools returning developer-authored\n   * constants) sets this to `true` so the LLM battery routes the result through its trusted\n   * envelope (`<trusted_content>` in the OpenAI Chat Completions battery).\n   *\n   * Trust is a property of the tool's output, not a property of how a particular battery is\n   * wired — putting the flag here means the trust signal travels with the tool wherever it is\n   * registered, no per-battery string lists, no name-matching to fail-open on typos.\n   *\n   * @defaultValue `false`\n   */\n  trusted?: boolean\n  /**\n   * Self-declared merge collision policy. Honoured by `ToolRegistry.merge` (NOT by\n   * `ToolRegistry.register`) when this tool collides with another of the same name.\n   *\n   * @remarks\n   * - `'throw'` (default): defer to the merge-level `options.onCollision`. If that is also\n   *   `'throw'`, the merge raises `E_TOOL_ALREADY_REGISTERED`. This matches the default behaviour\n   *   of `ToolRegistry.register`.\n   * - `'replace'`: this tool always wins the collision, regardless of the merge-level option.\n   * - `'keep'`: this tool always loses to any previously-registered tool of the same name.\n   *\n   * Forged artifact-query tools set this to `'replace'` so that merging multiple\n   * `Subclass.forgeTools(ctx)` outputs (whose base-method tools overlap by name) resolves\n   * silently — the descriptors, snapshot, and handler behaviour are interchangeable across\n   * subclasses, so replacement is a behavioural no-op.\n   *\n   * @defaultValue `'throw'`\n   */\n  onCollision?: 'throw' | 'replace' | 'keep'\n}\n\n/**\n * Validator schema for a {@link RawTool}.\n */\nconst rawToolSchema = validator.object<RawTool>({\n  name: validator.string().required(),\n  description: validator.string().required(),\n  inputSchema: validator\n    .any()\n    .custom((value, helpers) => {\n      if (validator.isSchema(value) && (value as any).type === 'object') return value\n      return helpers.error('any.invalid')\n    })\n    .required(),\n  handler: validator.function().required(),\n  artifactConstructor: validator\n    .any()\n    .custom((value, helpers) => {\n      if (typeof value !== 'function') return helpers.error('any.invalid')\n      // The resolver runs at validate time — well after the tool.ts ↔ spooled_artifact.ts ↔\n      // artifact_tool.ts module cycle has fully unwound — so invoking it is safe. Delegate the\n      // \"is this a SpooledArtifact-shaped constructor?\" check to the contract-level guard so\n      // there's one canonical duck-type test (mirrors `implementsSpoolReader`'s pattern).\n      let resolved: unknown\n      try {\n        resolved = (value as () => unknown)()\n      } catch {\n        return helpers.error('any.invalid')\n      }\n      if (implementsSpooledArtifactConstructor(resolved)) return value\n      return helpers.error('any.invalid')\n    })\n    .optional(),\n  meta: validator.object().pattern(validator.string(), validator.any()).default({}),\n  ephemeral: validator.boolean().default(false),\n  trusted: validator.boolean().default(false),\n  onCollision: validator.string().valid('throw', 'replace', 'keep').default('throw'),\n})\n\n/**\n * A tool definition that serves as the single source of truth for a callable tool: its name,\n * description, input schema, execution handler, and the {@link @nhtio/adk!SpooledArtifact} subclass that\n * wraps its serialised output.\n *\n * @typeParam A - The {@link @nhtio/adk!SpooledArtifact} subtype this tool's results should be wrapped in.\n *   Defaults to {@link @nhtio/adk!SpooledArtifact}.\n *\n * @remarks\n * The `inputSchema` is a `@nhtio/validation` schema. It is used at runtime to validate incoming\n * arguments before the handler is called, and its `.describe()` output provides all the metadata\n * needed to build a provider-specific LLM tool definition — annotate the schema with\n * `.description()`, `.note()`, `.example()` etc. once, and that information is available in both\n * contexts without duplication.\n *\n * The handler is private — invoke it only through `executor(ctx)` which validates args, fires\n * observability events (with a stable `callId` derived from the tool name and arguments), and\n * wraps handler errors in {@link @nhtio/adk!E_TOOL_DOWNSTREAM_ERROR}. The handler returns serialised bytes\n * (`string | Uint8Array`); persistence is the consumer's responsibility.\n *\n * `artifactConstructor` is the {@link @nhtio/adk!SpooledArtifact} subclass the consumer should use when\n * wrapping the handler's output into a `ToolCall.results` field. The author declares it once\n * on the tool instance; the consumer reads it when assembling persisted records.\n */\nexport class Tool<A extends SpooledArtifact = SpooledArtifact> {\n  /**\n   * Validator schema that accepts a {@link RawTool} object.\n   *\n   * @remarks\n   * Reusable fragment for any schema that needs to validate or nest a tool entry\n   * (e.g. `TurnRunnerConfig.tools`).\n   */\n  public static schema = rawToolSchema\n\n  /**\n   * Returns `true` if `value` is a {@link Tool} instance.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is a {@link Tool} instance.\n   */\n  public static isTool(value: unknown): value is Tool {\n    return isInstanceOf(value, 'Tool', Tool)\n  }\n\n  declare readonly name: string\n  declare readonly description: string\n  declare readonly inputSchema: Schema\n  declare readonly artifactConstructor: ArtifactConstructorResolver<A> | undefined\n  declare readonly meta: Registry\n  declare readonly ephemeral: boolean\n  declare readonly trusted: boolean\n  declare readonly onCollision: 'throw' | 'replace' | 'keep'\n\n  #name: string\n  #description: string\n  #inputSchema: Schema\n  #handler: ToolHandler\n  #artifactConstructor: ArtifactConstructorResolver<A> | undefined\n  #meta: Registry\n  #ephemeral: boolean\n  #trusted: boolean\n  #onCollision: 'throw' | 'replace' | 'keep'\n\n  /**\n   * @param raw - The raw tool input validated against `rawToolSchema`.\n   * @throws {@link @nhtio/adk!E_INVALID_INITIAL_TOOL_VALUE} when `raw` does not satisfy the schema.\n   */\n  constructor(raw: RawTool<A>) {\n    let resolved: RawTool<A> & {\n      meta: Record<string, unknown>\n      ephemeral: boolean\n      trusted: boolean\n      onCollision: 'throw' | 'replace' | 'keep'\n    }\n    try {\n      resolved = validateOrThrow<typeof resolved>(\n        rawToolSchema,\n        raw as RawTool,\n        true\n      ) as typeof resolved\n    } catch (err) {\n      throw new E_INVALID_INITIAL_TOOL_VALUE({ cause: isError(err) ? err : undefined })\n    }\n\n    this.#name = resolved.name\n    this.#description = resolved.description\n    this.#inputSchema = resolved.inputSchema\n    this.#handler = resolved.handler\n    this.#artifactConstructor = resolved.artifactConstructor as\n      | ArtifactConstructorResolver<A>\n      | undefined\n    this.#meta = new Registry(resolved.meta)\n    this.#ephemeral = resolved.ephemeral\n    this.#trusted = resolved.trusted\n    this.#onCollision = resolved.onCollision\n\n    Object.defineProperties(this, {\n      name: {\n        get: () => this.#name,\n        enumerable: true,\n        configurable: false,\n      },\n      description: {\n        get: () => this.#description,\n        enumerable: true,\n        configurable: false,\n      },\n      inputSchema: {\n        get: () => this.#inputSchema,\n        enumerable: true,\n        configurable: false,\n      },\n      artifactConstructor: {\n        get: () => this.#artifactConstructor,\n        enumerable: true,\n        configurable: false,\n      },\n      meta: {\n        get: () => this.#meta,\n        enumerable: true,\n        configurable: false,\n      },\n      ephemeral: {\n        get: () => this.#ephemeral,\n        enumerable: true,\n        configurable: false,\n      },\n      trusted: {\n        get: () => this.#trusted,\n        enumerable: true,\n        configurable: false,\n      },\n      onCollision: {\n        get: () => this.#onCollision,\n        enumerable: true,\n        configurable: false,\n      },\n    })\n  }\n\n  /**\n   * Validates `args` against the tool's input schema asynchronously.\n   *\n   * @remarks\n   * Async to support schemas with external validators (e.g. database lookups, API calls).\n   * A validation failure throws {@link @nhtio/adk!E_INVALID_TOOL_ARGS} — this indicates a programming error\n   * in the tool call loop, not a downstream failure.\n   *\n   * @param args - The arguments to validate.\n   * @returns The validated (and coerced) arguments.\n   * @throws {@link @nhtio/adk!E_INVALID_TOOL_ARGS} when `args` does not satisfy the input schema.\n   */\n  async validate(args: unknown): Promise<unknown> {\n    try {\n      return await asyncValidateOrThrow(this.#inputSchema, args)\n    } catch (err) {\n      if (isInstanceOf(err, 'ValidationException', ValidationException)) {\n        throw new E_INVALID_TOOL_ARGS({ cause: err })\n      }\n      throw err\n    }\n  }\n\n  /**\n   * Returns a bound executor function for this tool against the given turn context.\n   *\n   * @remarks\n   * The executor: (1) computes a stable `callId` as `sha256(canonicalStringify({tool, args}))`\n   * over the **raw, pre-validation args**, (2) validates `args` via {@link Tool.validate},\n   * (3) emits `toolExecutionStart` on the context (with the computed `callId`), (4) calls the\n   * handler, (5) emits `toolExecutionEnd` (with the same `callId`), (6) wraps any handler error\n   * in {@link @nhtio/adk!E_TOOL_DOWNSTREAM_ERROR} before re-throwing.\n   *\n   * The handler returns serialised bytes (`string | Uint8Array`) — persistence is the consumer's\n   * concern. Use {@link Tool.artifactConstructor} when wrapping the bytes into a\n   * `ToolCall.results` field.\n   *\n   * Pattern mirrors `Middleware.runner()` — call once per turn, reuse the returned function.\n   *\n   * @param ctx - The active turn context. Provides emit functions and turn ID.\n   * @returns An async function `(args) => Promise<string | Uint8Array>`.\n   */\n  executor(\n    ctx: DispatchContext\n  ): (args: unknown) => Promise<string | Uint8Array | Media | Media[]> {\n    return async (args: unknown): Promise<string | Uint8Array | Media | Media[]> => {\n      // Compute callId over raw args (pre-validation) so two invocations with the same\n      // (tool, raw args) produce the same identifier even if validation coerces values.\n      const callId = sha256(canonicalStringify({ tool: this.#name, args }))\n      const validatedArgs = await this.validate(args)\n      const startedAt = DateTime.now()\n      ctx.emitToolExecutionStart({\n        toolName: this.#name,\n        turnId: ctx.id,\n        callId,\n        args: validatedArgs,\n        startedAt,\n      })\n      try {\n        const result = await this.#handler(validatedArgs, ctx, this.#meta)\n        const endedAt = DateTime.now()\n        ctx.emitToolExecutionEnd({\n          toolName: this.#name,\n          turnId: ctx.id,\n          callId,\n          startedAt,\n          endedAt,\n          durationMs: endedAt.diff(startedAt).milliseconds,\n          isError: false,\n        })\n        return result\n      } catch (err) {\n        const endedAt = DateTime.now()\n        ctx.emitToolExecutionEnd({\n          toolName: this.#name,\n          turnId: ctx.id,\n          callId,\n          startedAt,\n          endedAt,\n          durationMs: endedAt.diff(startedAt).milliseconds,\n          isError: true,\n        })\n        throw new E_TOOL_DOWNSTREAM_ERROR({ cause: isError(err) ? err : undefined })\n      }\n    }\n  }\n\n  /**\n   * Returns a fully serialisable snapshot of this tool's definition.\n   *\n   * @remarks\n   * The `inputSchema` property is the result of calling `.describe()` on the raw schema — a plain\n   * object carrying all the annotation metadata (descriptions, notes, examples, types) without any\n   * validator functions. Use this to build provider-specific LLM tool definitions.\n   *\n   * @returns `{ name, description, inputSchema }` where `inputSchema` is the schema description.\n   */\n  describe(): { name: string; description: string; inputSchema: Description } {\n    return {\n      name: this.#name,\n      description: this.#description,\n      inputSchema: this.#inputSchema.describe(),\n    }\n  }\n}\n"],"mappings":";;;;;;;AAmBA,IAAM,mBAAmB;CACvB;CACA;CACA;CACA;CACA;CACA;CACA;AACF;;;;;;;;;;;;AAaA,IAAa,mCAAmC,UAAU,IAAI,EAAE,QAAQ,OAAO,YAAY;CACzF,IAAI,OAAO,UAAU,YAAY,OAAO,QAAQ,MAAM,aAAa;CACnE,MAAM,QAAS,MAAkC;CACjD,IAAI,UAAU,KAAA,KAAa,UAAU,MAAM,OAAO,QAAQ,MAAM,aAAa;CAC7E,IAAI,iBAAiB,OAAO,MAAM,OAAQ,MAAkC,OAAO,UAAU,GAC3F,OAAO;CAET,OAAO,QAAQ,MAAM,aAAa;AACpC,CAAC;;;;;;;;;;;;;AAcD,IAAa,wCACX,UAC4C;CAC5C,OAAO,aAAa,kCAAkC,KAAK;AAC7D;;;;;;ACmFA,IAAM,gBAAgB,UAAU,OAAgB;CAC9C,MAAM,UAAU,OAAO,EAAE,SAAS;CAClC,aAAa,UAAU,OAAO,EAAE,SAAS;CACzC,aAAa,UACV,IAAI,EACJ,QAAQ,OAAO,YAAY;EAC1B,IAAI,UAAU,SAAS,KAAK,KAAM,MAAc,SAAS,UAAU,OAAO;EAC1E,OAAO,QAAQ,MAAM,aAAa;CACpC,CAAC,EACA,SAAS;CACZ,SAAS,UAAU,SAAS,EAAE,SAAS;CACvC,qBAAqB,UAClB,IAAI,EACJ,QAAQ,OAAO,YAAY;EAC1B,IAAI,OAAO,UAAU,YAAY,OAAO,QAAQ,MAAM,aAAa;EAKnE,IAAI;EACJ,IAAI;GACF,WAAY,MAAwB;EACtC,QAAQ;GACN,OAAO,QAAQ,MAAM,aAAa;EACpC;EACA,IAAI,qCAAqC,QAAQ,GAAG,OAAO;EAC3D,OAAO,QAAQ,MAAM,aAAa;CACpC,CAAC,EACA,SAAS;CACZ,MAAM,UAAU,OAAO,EAAE,QAAQ,UAAU,OAAO,GAAG,UAAU,IAAI,CAAC,EAAE,QAAQ,CAAC,CAAC;CAChF,WAAW,UAAU,QAAQ,EAAE,QAAQ,KAAK;CAC5C,SAAS,UAAU,QAAQ,EAAE,QAAQ,KAAK;CAC1C,aAAa,UAAU,OAAO,EAAE,MAAM,SAAS,WAAW,MAAM,EAAE,QAAQ,OAAO;AACnF,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;AA0BD,IAAa,OAAb,MAAa,KAAkD;;;;;;;;CAQ7D,OAAc,SAAS;;;;;;;CAQvB,OAAc,OAAO,OAA+B;EAClD,OAAO,aAAa,OAAO,QAAQ,IAAI;CACzC;CAWA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;;;;;CAMA,YAAY,KAAiB;EAC3B,IAAI;EAMJ,IAAI;GACF,WAAW,gBACT,eACA,KACA,IACF;EACF,SAAS,KAAK;GACZ,MAAM,IAAI,6BAA6B,EAAE,OAAO,QAAQ,GAAG,IAAI,MAAM,KAAA,EAAU,CAAC;EAClF;EAEA,KAAKA,QAAQ,SAAS;EACtB,KAAKC,eAAe,SAAS;EAC7B,KAAKC,eAAe,SAAS;EAC7B,KAAKC,WAAW,SAAS;EACzB,KAAKC,uBAAuB,SAAS;EAGrC,KAAKC,QAAQ,IAAI,SAAS,SAAS,IAAI;EACvC,KAAKC,aAAa,SAAS;EAC3B,KAAKC,WAAW,SAAS;EACzB,KAAKC,eAAe,SAAS;EAE7B,OAAO,iBAAiB,MAAM;GAC5B,MAAM;IACJ,WAAW,KAAKR;IAChB,YAAY;IACZ,cAAc;GAChB;GACA,aAAa;IACX,WAAW,KAAKC;IAChB,YAAY;IACZ,cAAc;GAChB;GACA,aAAa;IACX,WAAW,KAAKC;IAChB,YAAY;IACZ,cAAc;GAChB;GACA,qBAAqB;IACnB,WAAW,KAAKE;IAChB,YAAY;IACZ,cAAc;GAChB;GACA,MAAM;IACJ,WAAW,KAAKC;IAChB,YAAY;IACZ,cAAc;GAChB;GACA,WAAW;IACT,WAAW,KAAKC;IAChB,YAAY;IACZ,cAAc;GAChB;GACA,SAAS;IACP,WAAW,KAAKC;IAChB,YAAY;IACZ,cAAc;GAChB;GACA,aAAa;IACX,WAAW,KAAKC;IAChB,YAAY;IACZ,cAAc;GAChB;EACF,CAAC;CACH;;;;;;;;;;;;;CAcA,MAAM,SAAS,MAAiC;EAC9C,IAAI;GACF,OAAO,MAAM,qBAAqB,KAAKN,cAAc,IAAI;EAC3D,SAAS,KAAK;GACZ,IAAI,aAAa,KAAK,uBAAuB,mBAAmB,GAC9D,MAAM,IAAI,oBAAoB,EAAE,OAAO,IAAI,CAAC;GAE9C,MAAM;EACR;CACF;;;;;;;;;;;;;;;;;;;;CAqBA,SACE,KACmE;EACnE,OAAO,OAAO,SAAkE;GAG9E,MAAM,SAAS,OAAO,mBAAmB;IAAE,MAAM,KAAKF;IAAO;GAAK,CAAC,CAAC;GACpE,MAAM,gBAAgB,MAAM,KAAK,SAAS,IAAI;GAC9C,MAAM,YAAY,SAAS,IAAI;GAC/B,IAAI,uBAAuB;IACzB,UAAU,KAAKA;IACf,QAAQ,IAAI;IACZ;IACA,MAAM;IACN;GACF,CAAC;GACD,IAAI;IACF,MAAM,SAAS,MAAM,KAAKG,SAAS,eAAe,KAAK,KAAKE,KAAK;IACjE,MAAM,UAAU,SAAS,IAAI;IAC7B,IAAI,qBAAqB;KACvB,UAAU,KAAKL;KACf,QAAQ,IAAI;KACZ;KACA;KACA;KACA,YAAY,QAAQ,KAAK,SAAS,EAAE;KACpC,SAAS;IACX,CAAC;IACD,OAAO;GACT,SAAS,KAAK;IACZ,MAAM,UAAU,SAAS,IAAI;IAC7B,IAAI,qBAAqB;KACvB,UAAU,KAAKA;KACf,QAAQ,IAAI;KACZ;KACA;KACA;KACA,YAAY,QAAQ,KAAK,SAAS,EAAE;KACpC,SAAS;IACX,CAAC;IACD,MAAM,IAAI,wBAAwB,EAAE,OAAO,QAAQ,GAAG,IAAI,MAAM,KAAA,EAAU,CAAC;GAC7E;EACF;CACF;;;;;;;;;;;CAYA,WAA4E;EAC1E,OAAO;GACL,MAAM,KAAKA;GACX,aAAa,KAAKC;GAClB,aAAa,KAAKC,aAAa,SAAS;EAC1C;CACF;AACF"}
+{"version":3,"file":"tool-CRZSUcdP.mjs","names":["#name","#description","#inputSchema","#handler","#artifactConstructor","#meta","#ephemeral","#trusted","#onCollision"],"sources":["../src/lib/contracts/spooled_artifact_constructor.ts","../src/lib/classes/tool.ts"],"sourcesContent":["import { validator } from '@nhtio/validation'\nimport { passesSchema } from '../utils/validation'\nimport type { SpooledArtifact } from '../classes/spooled_artifact'\n\n/**\n * Constructor signature for any {@link @nhtio/adk!SpooledArtifact} (the class itself or a subclass).\n *\n * @remarks\n * Re-declared here at the contract level so consumers — and the `Tool.artifactConstructor`\n * resolver validator in particular — can talk about the constructor shape without value-importing\n * the {@link @nhtio/adk!SpooledArtifact} class (which would close the `tool.ts` ↔ `spooled_artifact.ts` ↔\n * `artifact_tool.ts` module cycle at load time and TDZ-crash `ArtifactTool extends Tool`).\n *\n * @typeParam A - The {@link @nhtio/adk!SpooledArtifact} subtype the constructor produces.\n */\nexport type SpooledArtifactConstructorLike<A extends SpooledArtifact = SpooledArtifact> = new (\n  ...args: any[]\n) => A\n\nconst ARTIFACT_METHODS = [\n  'head',\n  'tail',\n  'grep',\n  'cat',\n  'byteLength',\n  'lineCount',\n  'estimateTokens',\n] as const\n\n/**\n * Validator schema used to validate a {@link SpooledArtifactConstructorLike} value.\n *\n * @remarks\n * Because the validator is invoked at validate-time (not at module-load), it is safe to inspect\n * the constructor's prototype here. The check is duck-typed: the value must be a function whose\n * `prototype` carries every canonical artifact instance method (`head`, `tail`, `grep`, `cat`,\n * `byteLength`, `lineCount`, `estimateTokens`). This mirrors {@link spoolReaderSchema}'s\n * cross-realm-safe duck-type pattern — `instanceof SpooledArtifact` would be tighter but would\n * force a value-import of the class and reopen the module cycle.\n */\nexport const spooledArtifactConstructorSchema = validator.any().custom((value, helpers) => {\n  if (typeof value !== 'function') return helpers.error('any.invalid')\n  const proto = (value as { prototype?: unknown }).prototype\n  if (proto === undefined || proto === null) return helpers.error('any.invalid')\n  if (ARTIFACT_METHODS.every((m) => typeof (proto as Record<string, unknown>)[m] === 'function')) {\n    return value\n  }\n  return helpers.error('any.invalid')\n})\n\n/**\n * Returns `true` if `value` is a constructor whose prototype carries every canonical\n * {@link @nhtio/adk!SpooledArtifact} instance method.\n *\n * @remarks\n * Duck-typed; does not use `instanceof SpooledArtifact`. Used by the `Tool.artifactConstructor`\n * resolver validator and any other site that needs to recognise a `SpooledArtifact`-like\n * constructor without pulling the class into its module-load graph.\n *\n * @param value - The value to test.\n * @returns `true` when `value` is a `SpooledArtifact`-shaped constructor.\n */\nexport const implementsSpooledArtifactConstructor = (\n  value: unknown\n): value is SpooledArtifactConstructorLike => {\n  return passesSchema(spooledArtifactConstructorSchema, value)\n}\n","import { DateTime } from 'luxon'\nimport { sha256 } from 'js-sha256'\nimport { Registry } from './registry'\nimport { validator } from '@nhtio/validation'\nimport { isInstanceOf, isError } from '../utils/guards'\nimport { canonicalStringify } from '../utils/canonical_json'\nimport { validateOrThrow, asyncValidateOrThrow, ValidationException } from '../utils/validation'\nimport { implementsSpooledArtifactConstructor } from '../contracts/spooled_artifact_constructor'\nimport {\n  E_INVALID_INITIAL_TOOL_VALUE,\n  E_INVALID_TOOL_ARGS,\n  E_TOOL_DOWNSTREAM_ERROR,\n} from '../exceptions/runtime'\nimport type { Media } from './media'\nimport type { Schema, Description } from '@nhtio/validation'\nimport type { DispatchContext } from '../contracts/dispatch_context'\nimport type { SpooledArtifact, SpooledArtifactConstructor } from './spooled_artifact'\n\n/**\n * A zero-arg function that returns the {@link @nhtio/adk!SpooledArtifactConstructor} the consumer should\n * use when wrapping this tool's serialised output into a `ToolCall.results` field.\n *\n * @remarks\n * Why a resolver (and not the constructor itself)? `tool.ts` participates in a module-load\n * cycle with `spooled_artifact.ts` and `artifact_tool.ts` (`ArtifactTool extends Tool` closes\n * the loop). Any eager value-level reference to `SpooledArtifact` in `tool.ts` would crash the\n * cycle with a TDZ error. A resolver lets `tool.ts` validate \"is a function\" at module-load\n * time and defer the actual constructor check to validate-time (which always runs after every\n * module body has executed). Wrap-sites invoke `tool.artifactConstructor?.() ?? SpooledArtifact`\n * to obtain the final constructor.\n */\nexport type ArtifactConstructorResolver<A extends SpooledArtifact = SpooledArtifact> =\n  () => SpooledArtifactConstructor<A>\n\n/**\n * The execution function for a {@link Tool}.\n *\n * @remarks\n * Receives the raw arguments passed to the executor, the active {@link @nhtio/adk!DispatchContext}, and the\n * tool's metadata registry.\n *\n * Return shapes:\n * - `string` / `Uint8Array` — opaque serialised output. The ADK does not persist the bytes\n *   itself; the consumer's executor middleware is responsible for storing them and wrapping\n *   them via `tool.artifactConstructor?.() ?? SpooledArtifact` when assembling the `ToolCall`\n *   record.\n * - {@link @nhtio/adk!Media} / `Media[]` — explicit-modality silo. Bypasses\n *   {@link Tool.artifactConstructor} — the handler returns the final result shape directly.\n *   The LLM battery renders each `Media` as a provider-specific content block.\n */\nexport type ToolHandler = (\n  args: unknown,\n  ctx: DispatchContext,\n  meta: Registry\n) => string | Uint8Array | Media | Media[] | Promise<string | Uint8Array | Media | Media[]>\n\n/**\n * Plain input object supplied to {@link Tool} at construction time.\n *\n * @typeParam A - The {@link @nhtio/adk!SpooledArtifact} subtype used to wrap this tool's results when\n *   the consumer assembles a `ToolCall.results` field. Defaults to {@link @nhtio/adk!SpooledArtifact}\n *   (plain text). Tools producing JSON output should set this to `SpooledJsonArtifact`; tools\n *   producing markdown should set it to `SpooledMarkdownArtifact`; consumers can also pass a\n *   custom subclass.\n */\nexport interface RawTool<A extends SpooledArtifact = SpooledArtifact> {\n  /** Unique identifier used in LLM tool definitions. Recommend lowercase snake_case. */\n  name: string\n  /** Human-readable description passed to the model to explain what the tool does. */\n  description: string\n  /** @nhtio/validation schema for the tool's input arguments. Annotate with `.description()`, `.note()`, `.example()` etc. to produce rich LLM tool definitions via `.describe()`. */\n  inputSchema: Schema\n  /** Execution function. Not exposed as a public property — invoke via `executor()`. */\n  handler: ToolHandler\n  /**\n   * Zero-arg resolver returning the {@link @nhtio/adk!SpooledArtifactConstructor} the consumer should use\n   * when wrapping this tool's serialised output into a `ToolCall.results` field. Optional —\n   * when omitted, wrap-sites fall back to {@link @nhtio/adk!SpooledArtifact} (plain text).\n   *\n   * @remarks\n   * Recommended call shape: `artifactConstructor: () => SpooledJsonArtifact`. The closure is\n   * the indirection that lets `tool.ts` validate this field without eagerly importing\n   * `SpooledArtifact` (which would crash the `tool.ts ↔ spooled_artifact.ts ↔ artifact_tool.ts`\n   * module-load cycle). At validate time the schema invokes the resolver and verifies its\n   * return value is a `SpooledArtifact`-derived constructor — wrong-shape resolvers throw\n   * {@link @nhtio/adk!E_INVALID_INITIAL_TOOL_VALUE}.\n   *\n   * Wrap-sites (storage batteries, scripted executors) read the constructor via\n   * `tool.artifactConstructor?.() ?? SpooledArtifact`.\n   */\n  artifactConstructor?: ArtifactConstructorResolver<A>\n  /** 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. */\n  meta?: Record<string, unknown>\n  /**\n   * When `true`, marks this tool as owned by a specific {@link @nhtio/adk!DispatchContext} so that\n   * `ToolRegistry.pruneEphemeral()` will drop it at ctx-completion.\n   *\n   * @remarks\n   * The flag is advisory at the `Tool` level — registries decide what to do with it. The canonical\n   * producer of ephemeral tools is `SpooledArtifact.forgeTools(ctx)`, which sets this to `true`\n   * on every artifact-query tool it emits.\n   *\n   * @defaultValue `false`\n   */\n  ephemeral?: boolean\n  /**\n   * When `true`, declares that this tool's output should be treated as **trusted developer/user\n   * intent** rather than as untrusted third-party text when surfaced to the model.\n   *\n   * @remarks\n   * LLM batteries read this flag per call when rendering tool-call results. The default\n   * untrusted envelope (e.g. `<untrusted_content>` in the OpenAI Chat Completions battery) is the\n   * secure-by-default treatment for arbitrary tool output. A tool whose output is authored by the\n   * user or operator (Q&A tools surfacing user-authored answers, human-in-the-loop approval\n   * gates, feedback-collection tools, configuration tools returning developer-authored\n   * constants) sets this to `true` so the LLM battery routes the result through its trusted\n   * envelope (`<trusted_content>` in the OpenAI Chat Completions battery).\n   *\n   * Trust is a property of the tool's output, not a property of how a particular battery is\n   * wired — putting the flag here means the trust signal travels with the tool wherever it is\n   * registered, no per-battery string lists, no name-matching to fail-open on typos.\n   *\n   * @defaultValue `false`\n   */\n  trusted?: boolean\n  /**\n   * Self-declared merge collision policy. Honoured by `ToolRegistry.merge` (NOT by\n   * `ToolRegistry.register`) when this tool collides with another of the same name.\n   *\n   * @remarks\n   * - `'throw'` (default): defer to the merge-level `options.onCollision`. If that is also\n   *   `'throw'`, the merge raises `E_TOOL_ALREADY_REGISTERED`. This matches the default behaviour\n   *   of `ToolRegistry.register`.\n   * - `'replace'`: this tool always wins the collision, regardless of the merge-level option.\n   * - `'keep'`: this tool always loses to any previously-registered tool of the same name.\n   *\n   * Forged artifact-query tools set this to `'replace'` so that merging multiple\n   * `Subclass.forgeTools(ctx)` outputs (whose base-method tools overlap by name) resolves\n   * silently — the descriptors, snapshot, and handler behaviour are interchangeable across\n   * subclasses, so replacement is a behavioural no-op.\n   *\n   * @defaultValue `'throw'`\n   */\n  onCollision?: 'throw' | 'replace' | 'keep'\n}\n\n/**\n * Validator schema for a {@link RawTool}.\n */\nconst rawToolSchema = validator.object<RawTool>({\n  name: validator.string().required(),\n  description: validator.string().required(),\n  inputSchema: validator\n    .any()\n    .custom((value, helpers) => {\n      if (validator.isSchema(value) && (value as any).type === 'object') return value\n      return helpers.error('any.invalid')\n    })\n    .required(),\n  handler: validator.function().required(),\n  artifactConstructor: validator\n    .any()\n    .custom((value, helpers) => {\n      if (typeof value !== 'function') return helpers.error('any.invalid')\n      // The resolver runs at validate time — well after the tool.ts ↔ spooled_artifact.ts ↔\n      // artifact_tool.ts module cycle has fully unwound — so invoking it is safe. Delegate the\n      // \"is this a SpooledArtifact-shaped constructor?\" check to the contract-level guard so\n      // there's one canonical duck-type test (mirrors `implementsSpoolReader`'s pattern).\n      let resolved: unknown\n      try {\n        resolved = (value as () => unknown)()\n      } catch {\n        return helpers.error('any.invalid')\n      }\n      if (implementsSpooledArtifactConstructor(resolved)) return value\n      return helpers.error('any.invalid')\n    })\n    .optional(),\n  meta: validator.object().pattern(validator.string(), validator.any()).default({}),\n  ephemeral: validator.boolean().default(false),\n  trusted: validator.boolean().default(false),\n  onCollision: validator.string().valid('throw', 'replace', 'keep').default('throw'),\n})\n\n/**\n * A tool definition that serves as the single source of truth for a callable tool: its name,\n * description, input schema, execution handler, and the {@link @nhtio/adk!SpooledArtifact} subclass that\n * wraps its serialised output.\n *\n * @typeParam A - The {@link @nhtio/adk!SpooledArtifact} subtype this tool's results should be wrapped in.\n *   Defaults to {@link @nhtio/adk!SpooledArtifact}.\n *\n * @remarks\n * The `inputSchema` is a `@nhtio/validation` schema. It is used at runtime to validate incoming\n * arguments before the handler is called, and its `.describe()` output provides all the metadata\n * needed to build a provider-specific LLM tool definition — annotate the schema with\n * `.description()`, `.note()`, `.example()` etc. once, and that information is available in both\n * contexts without duplication.\n *\n * The handler is private — invoke it only through `executor(ctx)` which validates args, fires\n * observability events (with a stable `callId` derived from the tool name and arguments), and\n * wraps handler errors in {@link @nhtio/adk!E_TOOL_DOWNSTREAM_ERROR}. The handler returns serialised bytes\n * (`string | Uint8Array`); persistence is the consumer's responsibility.\n *\n * `artifactConstructor` is the {@link @nhtio/adk!SpooledArtifact} subclass the consumer should use when\n * wrapping the handler's output into a `ToolCall.results` field. The author declares it once\n * on the tool instance; the consumer reads it when assembling persisted records.\n */\nexport class Tool<A extends SpooledArtifact = SpooledArtifact> {\n  /**\n   * Validator schema that accepts a {@link RawTool} object.\n   *\n   * @remarks\n   * Reusable fragment for any schema that needs to validate or nest a tool entry\n   * (e.g. `TurnRunnerConfig.tools`).\n   */\n  public static schema = rawToolSchema\n\n  /**\n   * Returns `true` if `value` is a {@link Tool} instance.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is a {@link Tool} instance.\n   */\n  public static isTool(value: unknown): value is Tool {\n    return isInstanceOf(value, 'Tool', Tool)\n  }\n\n  declare readonly name: string\n  declare readonly description: string\n  declare readonly inputSchema: Schema\n  declare readonly artifactConstructor: ArtifactConstructorResolver<A> | undefined\n  declare readonly meta: Registry\n  declare readonly ephemeral: boolean\n  declare readonly trusted: boolean\n  declare readonly onCollision: 'throw' | 'replace' | 'keep'\n\n  #name: string\n  #description: string\n  #inputSchema: Schema\n  #handler: ToolHandler\n  #artifactConstructor: ArtifactConstructorResolver<A> | undefined\n  #meta: Registry\n  #ephemeral: boolean\n  #trusted: boolean\n  #onCollision: 'throw' | 'replace' | 'keep'\n\n  /**\n   * @param raw - The raw tool input validated against `rawToolSchema`.\n   * @throws {@link @nhtio/adk!E_INVALID_INITIAL_TOOL_VALUE} when `raw` does not satisfy the schema.\n   */\n  constructor(raw: RawTool<A>) {\n    let resolved: RawTool<A> & {\n      meta: Record<string, unknown>\n      ephemeral: boolean\n      trusted: boolean\n      onCollision: 'throw' | 'replace' | 'keep'\n    }\n    try {\n      resolved = validateOrThrow<typeof resolved>(\n        rawToolSchema,\n        raw as RawTool,\n        true\n      ) as typeof resolved\n    } catch (err) {\n      throw new E_INVALID_INITIAL_TOOL_VALUE({ cause: isError(err) ? err : undefined })\n    }\n\n    this.#name = resolved.name\n    this.#description = resolved.description\n    this.#inputSchema = resolved.inputSchema\n    this.#handler = resolved.handler\n    this.#artifactConstructor = resolved.artifactConstructor as\n      | ArtifactConstructorResolver<A>\n      | undefined\n    this.#meta = new Registry(resolved.meta)\n    this.#ephemeral = resolved.ephemeral\n    this.#trusted = resolved.trusted\n    this.#onCollision = resolved.onCollision\n\n    Object.defineProperties(this, {\n      name: {\n        get: () => this.#name,\n        enumerable: true,\n        configurable: false,\n      },\n      description: {\n        get: () => this.#description,\n        enumerable: true,\n        configurable: false,\n      },\n      inputSchema: {\n        get: () => this.#inputSchema,\n        enumerable: true,\n        configurable: false,\n      },\n      artifactConstructor: {\n        get: () => this.#artifactConstructor,\n        enumerable: true,\n        configurable: false,\n      },\n      meta: {\n        get: () => this.#meta,\n        enumerable: true,\n        configurable: false,\n      },\n      ephemeral: {\n        get: () => this.#ephemeral,\n        enumerable: true,\n        configurable: false,\n      },\n      trusted: {\n        get: () => this.#trusted,\n        enumerable: true,\n        configurable: false,\n      },\n      onCollision: {\n        get: () => this.#onCollision,\n        enumerable: true,\n        configurable: false,\n      },\n    })\n  }\n\n  /**\n   * Validates `args` against the tool's input schema asynchronously.\n   *\n   * @remarks\n   * Async to support schemas with external validators (e.g. database lookups, API calls).\n   * A validation failure throws {@link @nhtio/adk!E_INVALID_TOOL_ARGS} — this indicates a programming error\n   * in the tool call loop, not a downstream failure.\n   *\n   * @param args - The arguments to validate.\n   * @returns The validated (and coerced) arguments.\n   * @throws {@link @nhtio/adk!E_INVALID_TOOL_ARGS} when `args` does not satisfy the input schema.\n   */\n  async validate(args: unknown): Promise<unknown> {\n    try {\n      return await asyncValidateOrThrow(this.#inputSchema, args)\n    } catch (err) {\n      if (isInstanceOf(err, 'ValidationException', ValidationException)) {\n        throw new E_INVALID_TOOL_ARGS({ cause: err })\n      }\n      throw err\n    }\n  }\n\n  /**\n   * Returns a bound executor function for this tool against the given turn context.\n   *\n   * @remarks\n   * The executor: (1) computes a stable `callId` as `sha256(canonicalStringify({tool, args}))`\n   * over the **raw, pre-validation args**, (2) validates `args` via {@link Tool.validate},\n   * (3) emits `toolExecutionStart` on the context (with the computed `callId`), (4) calls the\n   * handler, (5) emits `toolExecutionEnd` (with the same `callId`), (6) wraps any handler error\n   * in {@link @nhtio/adk!E_TOOL_DOWNSTREAM_ERROR} before re-throwing.\n   *\n   * The handler returns serialised bytes (`string | Uint8Array`) — persistence is the consumer's\n   * concern. Use {@link Tool.artifactConstructor} when wrapping the bytes into a\n   * `ToolCall.results` field.\n   *\n   * Pattern mirrors `Middleware.runner()` — call once per turn, reuse the returned function.\n   *\n   * @param ctx - The active turn context. Provides emit functions and turn ID.\n   * @returns An async function `(args) => Promise<string | Uint8Array>`.\n   */\n  executor(\n    ctx: DispatchContext\n  ): (args: unknown) => Promise<string | Uint8Array | Media | Media[]> {\n    return async (args: unknown): Promise<string | Uint8Array | Media | Media[]> => {\n      // Compute callId over raw args (pre-validation) so two invocations with the same\n      // (tool, raw args) produce the same identifier even if validation coerces values.\n      const callId = sha256(canonicalStringify({ tool: this.#name, args }))\n      const validatedArgs = await this.validate(args)\n      const startedAt = DateTime.now()\n      ctx.emitToolExecutionStart({\n        toolName: this.#name,\n        turnId: ctx.id,\n        callId,\n        args: validatedArgs,\n        startedAt,\n      })\n      try {\n        const result = await this.#handler(validatedArgs, ctx, this.#meta)\n        const endedAt = DateTime.now()\n        ctx.emitToolExecutionEnd({\n          toolName: this.#name,\n          turnId: ctx.id,\n          callId,\n          startedAt,\n          endedAt,\n          durationMs: endedAt.diff(startedAt).milliseconds,\n          isError: false,\n        })\n        return result\n      } catch (err) {\n        const endedAt = DateTime.now()\n        ctx.emitToolExecutionEnd({\n          toolName: this.#name,\n          turnId: ctx.id,\n          callId,\n          startedAt,\n          endedAt,\n          durationMs: endedAt.diff(startedAt).milliseconds,\n          isError: true,\n        })\n        throw new E_TOOL_DOWNSTREAM_ERROR({ cause: isError(err) ? err : undefined })\n      }\n    }\n  }\n\n  /**\n   * Returns a fully serialisable snapshot of this tool's definition.\n   *\n   * @remarks\n   * The `inputSchema` property is the result of calling `.describe()` on the raw schema — a plain\n   * object carrying all the annotation metadata (descriptions, notes, examples, types) without any\n   * validator functions. Use this to build provider-specific LLM tool definitions.\n   *\n   * @returns `{ name, description, inputSchema }` where `inputSchema` is the schema description.\n   */\n  describe(): { name: string; description: string; inputSchema: Description } {\n    return {\n      name: this.#name,\n      description: this.#description,\n      inputSchema: this.#inputSchema.describe(),\n    }\n  }\n}\n"],"mappings":"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"}

package/{tool-DIHzOZiV.js → tool-CX9vNHAw.js}

@@ -1,7 +1,7 @@
 require("./chunk-Ble4zEEl.js");
 const require_exceptions = require("./exceptions-CitH5wZI.js");
-const require_tool_registry = require("./tool_registry-CKk5ooxm.js");
-const require_runtime = require("./runtime-DyD9oQjH.js");
+const require_tool_registry = require("./tool_registry-CtCQ4Xoz.js");
+const require_runtime = require("./runtime-MFFcJrRv.js");
 let _nhtio_validation = require("@nhtio/validation");
 let luxon = require("luxon");
 let js_sha256 = require("js-sha256");
@@ -299,4 +299,4 @@ Object.defineProperty(exports, "Tool", {
 	}
 });
 
-//# sourceMappingURL=tool-DIHzOZiV.js.map
+//# sourceMappingURL=tool-CX9vNHAw.js.map