@nhtio/adk 1.20260913.0 → 1.20260924.0

package/thought-COeZTQ-B.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"thought-COeZTQ-B.cjs","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, isObject } from '../utils/guards'\nimport { ENCODE_METHOD, DECODE_METHOD } from '../utils/encoder_symbols'\nimport { E_INVALID_INITIAL_IDENTITY_VALUE } from '../exceptions/runtime'\nimport type { AdkEncodableSnapshot } from './encodable'\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 * Registry of every {@link Identity} genuinely constructed by this module, in this realm.\n *\n * @remarks\n * The brand that {@link identityOrRawIdentitySchema} trusts to bypass raw-object validation. A\n * {@link WeakSet} keyed by the instance is unforgeable (unlike {@link Identity.isIdentity}, which\n * falls back to a `constructor.name` comparison for cross-realm reach and therefore also accepts a\n * hand-rolled look-alike) and holds no strong reference. Every instance adds itself in the\n * constructor; membership means the instance carries real, intact private fields.\n */\nconst liveIdentities = new WeakSet<object>()\n\n/**\n * Public schema fragment that accepts either a plain {@link RawIdentity} object or an existing\n * {@link Identity} instance.\n *\n * @remarks\n * A genuinely-constructed live {@link Identity} passes through the custom branch UNCHANGED — mirroring\n * {@link @nhtio/adk!Tokenizable.schema}. This matters because Joi's object schema *clones* any value it\n * validates, and cloning an `Identity` produces a look-alike with the right prototype but no private\n * `#identifier` / `#representation` fields (the constructor never ran), which then throws on\n * `[ENCODE_METHOD]`. Returning the live instance verbatim keeps its private state intact so it encodes\n * and re-wraps losslessly.\n *\n * Only a **branded** instance (one this module actually constructed — see {@link liveIdentities})\n * bypasses validation. A bare `constructor.name === 'Identity'` is NOT enough: a look-alike or a\n * cross-realm instance is not in the brand set, so it falls through to {@link rawIdentitySchema},\n * which validates its fields (rejecting a malformed `representation`) rather than retaining an\n * unvalidated husk that would later produce invalid serialized state. Plain {@link RawIdentity}\n * objects fall through the same way.\n */\nconst identityOrRawIdentitySchema = validator\n  .alternatives(\n    validator.custom((value, helpers) => {\n      if (isObject(value) && liveIdentities.has(value)) {\n        return value\n      }\n      return helpers.error('any.invalid')\n    }),\n    rawIdentitySchema\n  )\n  .custom((value) => {\n    // A genuinely-branded live instance passes through the first alternative untouched. Anything\n    // else — a plain RawIdentity, a hand-rolled look-alike, or a FOREIGN/cross-realm `Identity`\n    // (a second copy of the package in the dependency tree) — arrives here as the field-validated\n    // output of `rawIdentitySchema`. Joi cloned it, so a foreign instance is now a husk that still\n    // carries an `Identity`-named prototype but has NO private fields; `Identity.isIdentity` accepts\n    // it (name/prototype fallback) yet `[ENCODE_METHOD]` throws reading the missing privates.\n    // Rebuild any non-branded value into a genuine LOCAL Identity so every consumer stores real,\n    // encodable private state regardless of where the value originated.\n    if (isObject(value) && liveIdentities.has(value)) {\n      return value\n    }\n    return new Identity(value as RawIdentity)\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 OR an existing {@link Identity} instance.\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. A locally branded {@link Identity} passes through\n   * unchanged (its private state is preserved, so it still encodes losslessly); foreign/cross-realm\n   * identities and plain {@link RawIdentity} values are validated field-by-field and rebuilt locally.\n   * See {@link identityOrRawIdentitySchema}.\n   */\n  public static schema = identityOrRawIdentitySchema\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    // Brand this genuinely-constructed instance so `identityOrRawIdentitySchema` can trust it to\n    // bypass raw-object validation. A look-alike or cross-realm object is never in this set.\n    liveIdentities.add(this)\n  }\n\n  /**\n   * Serialise this Identity into an `@nhtio/encoder` snapshot.\n   *\n   * @remarks\n   * Emits a {@link RawIdentity}-shaped object; `representation` is the live {@link @nhtio/adk!Tokenizable}\n   * instance (the encoder recurses into it). Round-trips via {@link Identity.[DECODE_METHOD]}, which\n   * re-validates through the constructor.\n   *\n   * @returns A {@link RawIdentity}-shaped snapshot.\n   */\n  [ENCODE_METHOD](): AdkEncodableSnapshot {\n    return {\n      identifier: this.#identifier,\n      representation: this.#representation,\n    }\n  }\n\n  /**\n   * Reconstruct an {@link Identity} from an {@link Identity.[ENCODE_METHOD]} snapshot.\n   *\n   * @param data - The snapshot produced by {@link Identity.[ENCODE_METHOD]}.\n   * @returns A fully-validated {@link Identity}.\n   */\n  static [DECODE_METHOD](data: AdkEncodableSnapshot): Identity {\n    return new Identity(data as RawIdentity)\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 { ENCODE_METHOD, DECODE_METHOD } from '../utils/encoder_symbols'\nimport type { DateTime } from 'luxon'\nimport type { AdkEncodableSnapshot } from './encodable'\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  /**\n   * Serialise this Memory into an `@nhtio/encoder` snapshot.\n   *\n   * @remarks\n   * Emits a {@link RawMemory}-shaped object; `content` is the live {@link @nhtio/adk!Tokenizable} and the\n   * temporal fields are live Luxon `DateTime` instances (the encoder recurses into both). Round-trips\n   * via {@link Memory.[DECODE_METHOD]}, which re-validates through the constructor.\n   *\n   * @returns A {@link RawMemory}-shaped snapshot.\n   */\n  [ENCODE_METHOD](): AdkEncodableSnapshot {\n    return {\n      id: this.#id,\n      content: this.#content,\n      confidence: this.#confidence,\n      importance: this.#importance,\n      createdAt: this.#createdAt,\n      updatedAt: this.#updatedAt,\n    }\n  }\n\n  /**\n   * Reconstruct a {@link Memory} from a {@link Memory.[ENCODE_METHOD]} snapshot.\n   *\n   * @param data - The snapshot produced by {@link Memory.[ENCODE_METHOD]}.\n   * @returns A fully-validated {@link Memory}.\n   */\n  static [DECODE_METHOD](data: AdkEncodableSnapshot): Memory {\n    return new Memory(data as RawMemory)\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 { ENCODE_METHOD, DECODE_METHOD } from '../utils/encoder_symbols'\nimport { E_INVALID_INITIAL_MESSAGE_VALUE } from '../exceptions/runtime'\nimport type { DateTime } from 'luxon'\nimport type { RawIdentity } from './identity'\nimport type { AdkEncodableSnapshot } from './encodable'\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\n          .any()\n          .required()\n          .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  /**\n   * Serialise this Message into an `@nhtio/encoder` snapshot.\n   *\n   * @remarks\n   * Emits a {@link RawMessage}-shaped object holding the live nested primitives — `content`\n   * ({@link @nhtio/adk!Tokenizable}), `attachments` ({@link @nhtio/adk!Media}[]), `identity`\n   * ({@link @nhtio/adk!Identity}), and Luxon temporal fields — which the encoder recurses into. A\n   * text-only message round-trips trivially; a message carrying {@link @nhtio/adk!Media} round-trips only\n   * if each attachment's reader is describable (a `fromWebFile`-backed attachment throws\n   * {@link @nhtio/adk!E_READER_NOT_DESCRIBABLE} at encode). The frozen attachments array is copied to a\n   * plain array for the snapshot. Round-trips via {@link Message.[DECODE_METHOD]}.\n   *\n   * @returns A {@link RawMessage}-shaped snapshot.\n   */\n  [ENCODE_METHOD](): AdkEncodableSnapshot {\n    return {\n      id: this.#id,\n      role: this.#role,\n      content: this.#content,\n      // Omit when empty: the schema's cross-field rule treats a present-but-empty `attachments`\n      // array as invalid (it must contain ≥1 entry when supplied). A text-only message has none.\n      ...(this.#attachments.length > 0 ? { attachments: [...this.#attachments] } : {}),\n      identity: this.#identity,\n      createdAt: this.#createdAt,\n      updatedAt: this.#updatedAt,\n    }\n  }\n\n  /**\n   * Reconstruct a {@link Message} from a {@link Message.[ENCODE_METHOD]} snapshot.\n   *\n   * @param data - The snapshot produced by {@link Message.[ENCODE_METHOD]}.\n   * @returns A fully-validated {@link Message}.\n   */\n  static [DECODE_METHOD](data: AdkEncodableSnapshot): Message {\n    return new Message(data as RawMessage)\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 { ENCODE_METHOD, DECODE_METHOD } from '../utils/encoder_symbols'\nimport { E_INVALID_INITIAL_THOUGHT_VALUE } from '../exceptions/runtime'\nimport type { DateTime } from 'luxon'\nimport type { RawIdentity } from './identity'\nimport type { AdkEncodableSnapshot } from './encodable'\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  /**\n   * The reasoning content as a plain string or an existing {@link @nhtio/adk!Tokenizable} instance.\n   *\n   * @remarks\n   * Required and non-empty in plain-text mode. In opaque mode ({@link RawThought.payload} present) it\n   * may be empty or omitted — the payload carries the meaning — and resolves to an empty\n   * {@link @nhtio/adk!Tokenizable}. `Thought.content` is therefore ALWAYS a `Tokenizable`, never\n   * `undefined`, so readers need no guard.\n   */\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?: string | 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` — string or {@link @nhtio/adk!Tokenizable}, via {@link @nhtio/adk!Tokenizable.emptyableSchema}.\n *   Required and non-empty in plain-text mode; may be empty or omitted in opaque mode (see the\n *   content-OR-payload rule below).\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 * Cross-field rule — a thought must carry meaning through EITHER its prose OR an opaque replay\n * `payload`. A NULLISH payload (`undefined` or `null`) carries no replay data and so counts as ABSENT\n * for both halves of the rule:\n * - `payload` ABSENT (plain-text mode) — `content` is REQUIRED and must be non-empty. The prose is\n *   the only thing the thought has; an empty one is indistinguishable from a bug.\n * - `payload` PRESENT (opaque mode) — `content` may be empty or omitted, and resolves to an empty\n *   {@link @nhtio/adk!Tokenizable}. The payload is what round-trips to the wire; `content` is kept only\n *   for token-accounting and human/observer inspection (see {@link RawThought.payload}), so a\n *   signed-but-textless provider thinking block is legitimate. Rejecting it would discard the\n *   payload's replay data — strictly worse than storing a thought with no prose.\n *\n * A present `payload` additionally REQUIRES a present `replayCompatibility`.\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    // Emptiness is adjudicated by the cross-field rule below, which needs to see `payload` to decide.\n    content: Tokenizable.emptyableSchema.optional(),\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    // A NULLISH payload carries no replay data, so it is opaque mode in NEITHER rule below. `null`\n    // reaches here easily — JSON round-tripping, a serializer normalising absent fields, a provider\n    // mapper assigning a nullish thinking block — and treating it as \"present\" would both demand a\n    // pointless `replayCompatibility` and, worse, waive the content requirement for a thought that has\n    // no prose AND no payload: the exact state the either-or exists to forbid.\n    const hasPayload = v.payload !== undefined && v.payload !== null\n    if (hasPayload && (v.replayCompatibility === undefined || v.replayCompatibility === null)) {\n      return helpers.error('any.invalid')\n    }\n    // content-OR-payload: only an opaque thought may go without prose. A Tokenizable counts as\n    // present without being unwrapped — a dynamic one would evaluate its callback just to be measured,\n    // and its emptiness is not knowable until prompt-assembly anyway.\n    if (!hasPayload) {\n      const hasContent = Tokenizable.isTokenizable(v.content)\n        ? true\n        : typeof v.content === 'string' && v.content.length > 0\n      if (!hasContent) {\n        return helpers.error('any.invalid')\n      }\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 — including when the raw input\n * omitted it or supplied `''`, which is legal in opaque-replay mode and resolves to an empty\n * {@link @nhtio/adk!Tokenizable}.\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  /**\n   * The reasoning content as a {@link @nhtio/adk!Tokenizable} for inline token estimation.\n   *\n   * @remarks\n   * Never `undefined` — an opaque thought constructed without prose carries an empty\n   * {@link @nhtio/adk!Tokenizable} here, so readers need no presence guard.\n   */\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    // Absent content is legal only in opaque mode (enforced by rawThoughtSchema). Resolve it to an\n    // EMPTY Tokenizable rather than leaving it undefined so `content` stays a total field — every\n    // reader can call `.toString()` / measure it without a guard.\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  /**\n   * Serialise this Thought into an `@nhtio/encoder` snapshot.\n   *\n   * @remarks\n   * Emits a {@link RawThought}-shaped object; `content` is the live {@link @nhtio/adk!Tokenizable},\n   * `identity` the live {@link @nhtio/adk!Identity}, and the temporal fields live Luxon `DateTime`s (the\n   * encoder recurses into each). The vendor-opaque `payload` is passed through as-is — if it holds a\n   * value the encoder cannot serialise, encode throws (standard encoder behaviour). Round-trips via\n   * {@link Thought.[DECODE_METHOD]}, which re-validates through the constructor.\n   *\n   * @returns A {@link RawThought}-shaped snapshot.\n   */\n  [ENCODE_METHOD](): AdkEncodableSnapshot {\n    return {\n      id: this.#id,\n      content: this.#content,\n      identity: this.#identity,\n      payload: this.#payload,\n      replayCompatibility: this.#replayCompatibility,\n      createdAt: this.#createdAt,\n      updatedAt: this.#updatedAt,\n    }\n  }\n\n  /**\n   * Reconstruct a {@link Thought} from a {@link Thought.[ENCODE_METHOD]} snapshot.\n   *\n   * @param data - The snapshot produced by {@link Thought.[ENCODE_METHOD]}.\n   * @returns A fully-validated {@link Thought}.\n   */\n  static [DECODE_METHOD](data: AdkEncodableSnapshot): Thought {\n    return new Thought(data as RawThought)\n  }\n}\n"],"mappings":"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"}

package/{tokenizable-KwA7jyGQ.js → tokenizable-DDIdXbJN.cjs}

@@ -1,5 +1,5 @@
-const require_exceptions = require("./exceptions-DrHnAGQz.js");
-const require_guards = require("./guards-05Uq3J4M.js");
+const require_exceptions = require("./exceptions-DrHnAGQz.cjs");
+const require_guards = require("./guards-5-XmJgD2.cjs");
 let _nhtio_validation = require("@nhtio/validation");
 let js_tiktoken = require("js-tiktoken");
 let llama_tokenizer_js = require("llama-tokenizer-js");
@@ -1130,4 +1130,4 @@ Object.defineProperty(exports, "runWithEstimationWarnings", {
 	}
 });
 
-//# sourceMappingURL=tokenizable-KwA7jyGQ.js.map
+//# sourceMappingURL=tokenizable-DDIdXbJN.cjs.map

package/tokenizable-DDIdXbJN.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenizable-DDIdXbJN.cjs","names":["#evaluator","#value","#cache","#ctxCache"],"sources":["../src/lib/exceptions/runtime.ts","../src/lib/utils/encoder_symbols.ts","../src/lib/utils/estimation_context.ts","../src/lib/classes/tokenizable.ts"],"sourcesContent":["import { createException } from '../utils/exceptions'\n\n/**\n * Thrown by {@link @nhtio/adk!TurnRunner} when the supplied config object fails schema validation at\n * construction time.\n *\n * @remarks\n * Marked fatal — a misconfigured runner must not be allowed to execute turns.\n *\n * The single printf argument carries the validator's field-level detail (e.g.\n * `\"storeMediaBytesCallback is required\"`) so a misconfiguration names the offending field\n * instead of failing opaquely. The underlying `ValidationError` is also attached on `cause`.\n *\n * @group Turn Runner Construction\n */\nexport const E_INVALID_TURN_RUNNER_CONFIG = createException<[string]>(\n  'E_INVALID_TURN_RUNNER_CONFIG',\n  'The turn runner cannot be instantiated with the provided configuration: %s',\n  'E_INVALID_TURN_RUNNER_CONFIG',\n  529,\n  true\n)\n\n/**\n * Thrown by {@link @nhtio/adk!TurnRunner} when the {@link @nhtio/adk!TurnContext} supplied to `run` fails schema\n * validation.\n *\n * @remarks\n * Marked fatal — an invalid context indicates a programming error in the caller, not a\n * recoverable runtime condition. Thrown synchronously out of `run()` before `turnStart` is\n * emitted.\n *\n * @group Turn Input Validation\n */\nexport const E_INVALID_TURN_CONTEXT = createException(\n  'E_INVALID_TURN_CONTEXT',\n  'The turn runner received an invalid context object.',\n  'E_INVALID_TURN_CONTEXT',\n  529,\n  true\n)\n\n/**\n * Emitted (via the `error` event) when a non-abort error propagates out of the input\n * middleware pipeline during {@link @nhtio/adk!TurnRunner.run}.\n *\n * @remarks\n * Not fatal — the turn runner emits this on the `error` event rather than throwing, so\n * registered listeners can handle or log the failure without crashing the pipeline. Dispatch\n * and output middleware are skipped; `turnEnd` still fires.\n *\n * @group Pipelines\n */\nexport const E_INPUT_PIPELINE_ERROR = createException(\n  'E_INPUT_PIPELINE_ERROR',\n  'An error occurred in the input pipeline.',\n  'E_INPUT_PIPELINE_ERROR',\n  500,\n  false\n)\n\n/**\n * Emitted (via the `error` event) when a non-abort error propagates out of the output\n * middleware pipeline during {@link @nhtio/adk!TurnRunner.run}.\n *\n * @remarks\n * Not fatal — the turn runner emits this on the `error` event rather than throwing, so\n * registered listeners can handle or log the failure without crashing the pipeline. `turnEnd`\n * still fires.\n *\n * @group Pipelines\n */\nexport const E_OUTPUT_PIPELINE_ERROR = createException(\n  'E_OUTPUT_PIPELINE_ERROR',\n  'An error occurred in the output pipeline.',\n  'E_OUTPUT_PIPELINE_ERROR',\n  500,\n  false\n)\n\n/**\n * Emitted (via the `error` event) when a middleware pipeline resolves without reaching its\n * terminal handler and without the turn being aborted. Indicates that some middleware\n * returned without calling `next` and without signalling a deliberate refusal via the turn's\n * abort controller.\n *\n * @remarks\n * Not fatal — the runner emits this on the `error` event so the failure is observable, then\n * proceeds to short-circuit the remainder of the turn the same way any other pipeline error\n * would. The constructor takes a single positional argument identifying the pipeline that\n * short-circuited: one of `'turn-input'`, `'turn-output'`, `'dispatch-input'`, or `'dispatch-output'`.\n *\n * Deliberate refusals should call `ctx.abort(reason)`, which sets the `'aborted'` outcome\n * instead of emitting this error.\n *\n * @warning\n * This is a **detection condition**, not a thrown exception. The runner constructs and emits\n * the code itself when it detects a missing `next()` on the unwind — nothing in user code\n * throws it. Upstream post-steps still run normally.\n *\n * @example\n * ```ts\n * throw new E_PIPELINE_SHORT_CIRCUITED(['turn-input'])\n * ```\n *\n * @group Pipelines\n */\nexport const E_PIPELINE_SHORT_CIRCUITED = createException<[string]>(\n  'E_PIPELINE_SHORT_CIRCUITED',\n  \"The '%s' middleware pipeline short-circuited without calling next or aborting the turn.\",\n  'E_PIPELINE_SHORT_CIRCUITED',\n  500,\n  false\n)\n\n/**\n * Thrown when a registry is initialised with a value that is defined but not a plain object.\n *\n * @remarks\n * Registries expect either `undefined` (empty start) or a plain object as their initial value.\n * Passing a primitive, array, class instance, or other non-object signals a programming error\n * in the caller.\n *\n * @group Primitive Validation\n */\nexport const E_INVALID_INITIAL_REGISTRY_VALUE = createException(\n  'E_INVALID_INITIAL_REGISTRY_VALUE',\n  'Attempted to initialize a registry with a defined non-object value.',\n  'E_INVALID_INITIAL_REGISTRY_VALUE',\n  500,\n  true\n)\n\n/**\n * Thrown when a {@link @nhtio/adk!Memory} is initialised with a value that fails schema validation.\n *\n * @remarks\n * `Memory` requires all fields — `id`, `content`, `confidence`, `importance`, `createdAt`,\n * `updatedAt` — to be present and of the correct type. Passing an incomplete or incorrectly\n * typed object signals a programming error in the caller, not a recoverable runtime condition.\n *\n * @group Primitive Validation\n */\nexport const E_INVALID_INITIAL_MEMORY_VALUE = createException(\n  'E_INVALID_INITIAL_MEMORY_VALUE',\n  'Attempted to initialize a memory with an invalid value.',\n  'E_INVALID_INITIAL_MEMORY_VALUE',\n  500,\n  true\n)\n\n/**\n * Thrown when a tool call and retrievable eligible for artifact forging share an id.\n */\nexport const E_ARTIFACT_ID_COLLISION = createException<[string]>(\n  'E_ARTIFACT_ID_COLLISION',\n  'Artifact id collision: the tool call and retrievable with id \"%s\" both identify eligible artifacts.',\n  'E_ARTIFACT_ID_COLLISION',\n  409,\n  true\n)\n\n/**\n * Thrown when a {@link @nhtio/adk!Retrievable} is initialised with a value that fails schema validation.\n *\n * @remarks\n * `Retrievable` requires `id`, `content`, `trustTier`, `createdAt`, and `updatedAt` to be present\n * and of the correct type, and `trustTier` must be one of `'first-party'`, `'third-party-public'`,\n * or `'third-party-private'`. The `trustTier` decision must be made consciously by the retrieval\n * middleware at construction time — there is no default. Passing an incomplete or incorrectly\n * typed object signals a programming error in the caller, not a recoverable runtime condition.\n *\n * @group Primitive Validation\n */\nexport const E_INVALID_INITIAL_RETRIEVABLE_VALUE = createException(\n  'E_INVALID_INITIAL_RETRIEVABLE_VALUE',\n  'Invalid initial value supplied to Retrievable constructor.',\n  'E_INVALID_INITIAL_RETRIEVABLE_VALUE',\n  500,\n  true\n)\n\n/**\n * Thrown when a {@link @nhtio/adk!Message} is initialised with a value that fails schema validation.\n *\n * @remarks\n * `Message` requires `id`, `role` (`user` or `assistant`), `content`, `createdAt`, and\n * `updatedAt` to be present and of the correct type. Passing an incomplete or incorrectly\n * typed object signals a programming error in the caller, not a recoverable runtime condition.\n *\n * @group Primitive Validation\n */\nexport const E_INVALID_INITIAL_MESSAGE_VALUE = createException(\n  'E_INVALID_INITIAL_MESSAGE_VALUE',\n  'Attempted to initialize a message with an invalid value.',\n  'E_INVALID_INITIAL_MESSAGE_VALUE',\n  500,\n  true\n)\n\n/**\n * Thrown when an {@link @nhtio/adk!Identity} is initialised with a value that fails schema validation.\n *\n * @remarks\n * `Identity` requires both `identifier` (string or number) and `representation` (string or\n * {@link @nhtio/adk!Tokenizable}) to be present and of the correct type. Passing an incomplete or\n * incorrectly typed object signals a programming error in the caller.\n *\n * @group Primitive Validation\n */\nexport const E_INVALID_INITIAL_IDENTITY_VALUE = createException(\n  'E_INVALID_INITIAL_IDENTITY_VALUE',\n  'Attempted to initialize an identity with an invalid value.',\n  'E_INVALID_INITIAL_IDENTITY_VALUE',\n  500,\n  true\n)\n\n/**\n * Thrown when a {@link @nhtio/adk!Thought} is initialised with a value that fails schema validation.\n *\n * @remarks\n * `Thought` requires `id`, `content`, `createdAt`, and `updatedAt` to be present and of the\n * correct type. Passing an incomplete or incorrectly typed object signals a programming error\n * in the caller, not a recoverable runtime condition.\n *\n * @group Primitive Validation\n */\nexport const E_INVALID_INITIAL_THOUGHT_VALUE = createException(\n  'E_INVALID_INITIAL_THOUGHT_VALUE',\n  'Attempted to initialize a thought with an invalid value.',\n  'E_INVALID_INITIAL_THOUGHT_VALUE',\n  500,\n  true\n)\n\n/**\n * Thrown when a {@link @nhtio/adk!TurnGate} is constructed with a value that fails schema validation.\n *\n * @remarks\n * Fatal — bad construction arguments indicate a programming error in the caller.\n *\n * @group Gates\n */\nexport const E_INVALID_INITIAL_TURN_GATE_VALUE = createException(\n  'E_INVALID_INITIAL_TURN_GATE_VALUE',\n  'Attempted to initialize a turn gate with an invalid value.',\n  'E_INVALID_INITIAL_TURN_GATE_VALUE',\n  500,\n  true\n)\n\n/**\n * Thrown synchronously in the caller's context when {@link @nhtio/adk!TurnGate.resolve} is called with a\n * value that fails the gate's schema.\n *\n * @remarks\n * Fatal — passing the wrong type to `resolve()` is a programming error. The internal promise is\n * NOT settled when this is thrown; the gate remains open.\n *\n * @group Gates\n */\nexport const E_INVALID_TURN_GATE_RESOLUTION = createException(\n  'E_INVALID_TURN_GATE_RESOLUTION',\n  'The value supplied to TurnGate.resolve() failed schema validation.',\n  'E_INVALID_TURN_GATE_RESOLUTION',\n  500,\n  true\n)\n\n/**\n * Thrown (as a rejection reason) when a {@link @nhtio/adk!TurnGate} times out before being resolved.\n *\n * @remarks\n * Not fatal — a timeout is a recoverable runtime condition; the caller may retry or surface it\n * to the user.\n *\n * @warning\n * A timeout does **not** cancel the external event or clear any remote queue. The gate closes\n * locally, but whatever external system was expected to call `gate.resolve()` may still fire\n * later. Orphaned external state must be handled by the caller.\n *\n * @group Gates\n */\nexport const E_TURN_GATE_TIMEOUT = createException(\n  'E_TURN_GATE_TIMEOUT',\n  'The turn gate timed out before being resolved.',\n  'E_TURN_GATE_TIMEOUT',\n  408,\n  false\n)\n\n/**\n * Thrown (as a rejection reason) when a {@link @nhtio/adk!TurnGate} is aborted — either because the turn's\n * `AbortSignal` fired or because {@link @nhtio/adk!TurnGate.abort} was called directly.\n *\n * @remarks\n * Not fatal — abort is an intentional cancellation, not an error in the caller.\n *\n * @group Gates\n */\nexport const E_TURN_GATE_ABORTED = createException(\n  'E_TURN_GATE_ABORTED',\n  'The turn gate was aborted before being resolved.',\n  'E_TURN_GATE_ABORTED',\n  499,\n  false\n)\n\n/**\n * Thrown when a {@link @nhtio/adk!SpooledArtifact} is constructed with a value that does not implement the\n * {@link @nhtio/adk!SpoolReader} interface.\n *\n * @remarks\n * Validated at construction time via {@link @nhtio/adk!implementsSpoolReader}. Passing anything that lacks\n * `line`, `byteLength`, or `lineCount` as callable functions signals a programming error in the\n * caller.\n *\n * @group Artifacts\n */\nexport const E_NOT_A_SPOOL_READER = createException(\n  'E_NOT_A_SPOOL_READER',\n  'The provided value does not implement the SpoolReader interface.',\n  'E_NOT_A_SPOOL_READER',\n  500,\n  true\n)\n\n/**\n * Thrown when a Media is constructed with a value that does not implement the MediaReader\n * interface.\n *\n * @remarks\n * Validated at construction time. Passing anything that lacks `stream` or `byteLength` as\n * callable functions signals a programming error in the caller.\n *\n * @group Artifacts\n */\nexport const E_NOT_A_MEDIA_READER = createException(\n  'E_NOT_A_MEDIA_READER',\n  'The provided value does not implement the MediaReader interface.',\n  'E_NOT_A_MEDIA_READER',\n  500,\n  true\n)\n\n/**\n * Thrown when a Media is initialised with a value that fails schema validation.\n *\n * @remarks\n * Fatal — bad construction arguments indicate a programming error in the caller.\n *\n * @group Artifacts\n */\nexport const E_INVALID_INITIAL_MEDIA_VALUE = createException(\n  'E_INVALID_INITIAL_MEDIA_VALUE',\n  'Attempted to initialize a media with an invalid value.',\n  'E_INVALID_INITIAL_MEDIA_VALUE',\n  500,\n  true\n)\n\n/**\n * Thrown when a {@link @nhtio/adk!ToolCall} is initialised with a value that fails schema validation.\n *\n * @remarks\n * `ToolCall` requires `id`, `tool`, `args`, `checksum`, `isComplete`, `isError`, `createdAt`,\n * and `updatedAt` to be present and of the correct type. Passing an incomplete or incorrectly\n * typed object signals a programming error in the caller, not a recoverable runtime condition.\n *\n * @group Primitive Validation\n */\nexport const E_INVALID_INITIAL_TOOL_CALL_VALUE = createException(\n  'E_INVALID_INITIAL_TOOL_CALL_VALUE',\n  'Attempted to initialize a tool call with an invalid value.',\n  'E_INVALID_INITIAL_TOOL_CALL_VALUE',\n  500,\n  true\n)\n\n/**\n * Thrown when a {@link @nhtio/adk!Tool} is constructed with a value that fails schema validation.\n *\n * @remarks\n * Fatal — bad construction arguments indicate a programming error in the caller.\n *\n * @group Tools\n */\nexport const E_INVALID_INITIAL_TOOL_VALUE = createException(\n  'E_INVALID_INITIAL_TOOL_VALUE',\n  'Attempted to initialize a tool with an invalid value.',\n  'E_INVALID_INITIAL_TOOL_VALUE',\n  500,\n  true\n)\n\n/**\n * Thrown synchronously when {@link @nhtio/adk!Tool.validate} is called with arguments that fail the tool's\n * input schema.\n *\n * @remarks\n * Not fatal — an arg validation failure in the tool call loop is a caller mistake that can be\n * surfaced as an error response. The tool handler is NOT called when this is thrown.\n *\n * @group Tools\n */\nexport const E_INVALID_TOOL_ARGS = createException(\n  'E_INVALID_TOOL_ARGS',\n  'The arguments supplied to the tool failed input schema validation.',\n  'E_INVALID_TOOL_ARGS',\n  422,\n  false\n)\n\n/**\n * Thrown (as a rejection reason) when a {@link @nhtio/adk!Tool}'s handler throws during execution.\n *\n * @remarks\n * Not fatal — a downstream tool failure is a recoverable runtime condition. The tool call loop\n * catches this error specifically to report the failure back to the model rather than crashing\n * the pipeline.\n *\n * @group Tools\n */\nexport const E_TOOL_DOWNSTREAM_ERROR = createException(\n  'E_TOOL_DOWNSTREAM_ERROR',\n  'The tool handler threw an error during execution.',\n  'E_TOOL_DOWNSTREAM_ERROR',\n  500,\n  false\n)\n\n/**\n * Thrown when {@link @nhtio/adk!ToolRegistry.register} is called for a tool name that is already registered\n * and `overwrite` is not `true`.\n *\n * @remarks\n * Fatal — accidentally overwriting a registered tool indicates a programming error. Pass\n * `overwrite: true` to replace an existing tool intentionally.\n *\n * @group Tools\n */\nexport const E_TOOL_ALREADY_REGISTERED = createException(\n  'E_TOOL_ALREADY_REGISTERED',\n  'A tool with this name is already registered. Pass overwrite: true to replace it.',\n  'E_TOOL_ALREADY_REGISTERED',\n  409,\n  true\n)\n\n/**\n * Thrown when {@link @nhtio/adk!DispatchContext} is constructed with a value that fails schema validation.\n *\n * @remarks\n * Fatal — bad construction arguments indicate a programming error in the caller.\n *\n * @group Dispatch\n */\nexport const E_INVALID_LLM_EXECUTION_CONTEXT = createException(\n  'E_INVALID_LLM_EXECUTION_CONTEXT',\n  'The LLM execution context cannot be instantiated with the provided value.',\n  'E_INVALID_LLM_EXECUTION_CONTEXT',\n  529,\n  true\n)\n\n/**\n * Thrown (as a rejection reason) when {@link @nhtio/adk!DispatchContext.waitFor} is called on a\n * standalone context that was constructed without a `waitFor` function.\n *\n * @remarks\n * Not fatal — the caller can catch this and handle the case where gate suspension is not\n * supported for this execution context.\n *\n * @group Dispatch\n */\nexport const E_LLM_EXECUTION_GATE_NOT_SUPPORTED = createException(\n  'E_LLM_EXECUTION_GATE_NOT_SUPPORTED',\n  'waitFor was called on a standalone DispatchContext with no gate function provided.',\n  'E_LLM_EXECUTION_GATE_NOT_SUPPORTED',\n  501,\n  false\n)\n\n/**\n * Thrown when {@link @nhtio/adk!DispatchContext.ack} or {@link @nhtio/adk!DispatchContext.nack} is called on a\n * context that has already been signalled.\n *\n * @remarks\n * Fatal — signalling twice is a programming error in the caller. The first signal wins; the\n * second call is rejected loudly so callers cannot accidentally race between ack and nack.\n *\n * @danger\n * Signalling is **not** silently idempotent. The first `ack()` or `nack()` wins; the second\n * throws immediately. Guard with `if (!ctx.isSignalled)` when more than one seam may signal.\n *\n * @group Dispatch\n */\nexport const E_LLM_EXECUTION_ALREADY_SIGNALLED = createException(\n  'E_LLM_EXECUTION_ALREADY_SIGNALLED',\n  'ack() or nack() was called on an DispatchContext that has already been signalled.',\n  'E_LLM_EXECUTION_ALREADY_SIGNALLED',\n  500,\n  true\n)\n\n/**\n * Thrown when {@link @nhtio/adk!DispatchRunner.dispatch} receives an input that fails schema validation.\n *\n * @remarks\n * Fatal — invalid dispatch input indicates a programming error in the caller.\n *\n * @group Dispatch\n */\nexport const E_INVALID_LLM_DISPATCH_INPUT = createException(\n  'E_INVALID_LLM_DISPATCH_INPUT',\n  'The LLM execution runner received an invalid dispatch input.',\n  'E_INVALID_LLM_DISPATCH_INPUT',\n  529,\n  true\n)\n\n/**\n * Emitted (via the observability `error` hook) and re-thrown when a non-abort error propagates\n * out of the input or output middleware pipeline during {@link @nhtio/adk!DispatchRunner.dispatch}.\n *\n * @remarks\n * Not fatal — pipeline errors are recoverable runtime conditions. `dispatch()` rejects with this\n * exception so callers can handle the failure via try/catch. Both `dispatchInputPipeline` and\n * `dispatchOutputPipeline` share this one code — the runner does not split input vs. output at\n * this layer.\n *\n * @group Pipelines\n */\nexport const E_DISPATCH_PIPELINE_ERROR = createException(\n  'E_DISPATCH_PIPELINE_ERROR',\n  'An error occurred in an LLM execution pipeline.',\n  'E_DISPATCH_PIPELINE_ERROR',\n  500,\n  false\n)\n\n/**\n * Emitted (via the observability `error` hook) and re-thrown when the user-supplied executor\n * callback throws during {@link @nhtio/adk!DispatchRunner.dispatch}.\n *\n * @remarks\n * Not fatal — executor errors are recoverable runtime conditions. `dispatch()` rejects with this\n * exception so callers can handle the failure via try/catch.\n *\n * @group Dispatch\n */\nexport const E_LLM_EXECUTION_EXECUTOR_ERROR = createException(\n  'E_LLM_EXECUTION_EXECUTOR_ERROR',\n  'The LLM execution executor callback threw an error.',\n  'E_LLM_EXECUTION_EXECUTOR_ERROR',\n  500,\n  false\n)\n\n/**\n * Thrown when `encode()`-ing a reader-backed primitive ({@link @nhtio/adk!Media},\n * {@link @nhtio/adk!SpooledArtifact}) whose underlying reader cannot describe itself.\n *\n * @remarks\n * The encoder serialises reader-backed primitives as **handles**, not bytes: the reader emits a\n * `{ tag, locator }` descriptor (via its optional `describe()` method) and decode re-binds it through a\n * registered resolver. A reader with no `describe()` has no serialisable handle — there is nothing to\n * write down. The single printf argument names the offending field (e.g. `\"reader\"`).\n *\n * This is deliberately not silent: dropping the reader would yield a `Media`/`SpooledArtifact` that\n * decodes into a handle pointing at nothing. The framework refuses to fabricate that. The canonical\n * trigger is a `fromWebFile`-backed `Media` — a browser `Blob` is not re-openable across a\n * serialisation boundary, and the encoder is synchronous so it cannot drain the bytes inline. Re-wrap\n * the bytes in a describable reader (e.g. persist to a spool/media store) before encoding.\n *\n * Not fatal — an un-encodable value is a caller condition, not a runner failure.\n *\n * @group Primitive Validation\n */\nexport const E_READER_NOT_DESCRIBABLE = createException<[string]>(\n  'E_READER_NOT_DESCRIBABLE',\n  'Cannot encode this value: its %s reader does not implement describe(), so it has no serialisable handle. Back it with a describable reader (a spool/media store) before encoding.',\n  'E_READER_NOT_DESCRIBABLE',\n  422,\n  false\n)\n\n/**\n * Thrown when `decode()`-ing a reader handle whose `tag` has no registered resolver.\n *\n * @remarks\n * A reader descriptor's `tag` (e.g. `\"spool:flydrive\"`, `\"media:in-memory\"`) names the resolver that\n * re-binds the handle to a live reader. In-memory and fetch resolvers auto-register when the\n * `@nhtio/adk/batteries/encoding` battery loads; durable-store resolvers (flydrive, OPFS) must be\n * registered by the consumer **with the live `Disk`/OPFS root** before decoding, because the locator\n * carries only the key — not the binding. The single printf argument is the unresolved `tag`.\n *\n * The fix is always the same: call `registerSpoolReaderResolver(tag, …)` /\n * `registerMediaReaderResolver(tag, …)` (re-exported from the encoding battery) at application startup,\n * supplying the same ambient store the bytes were written to.\n *\n * Not fatal — a missing resolver is a wiring condition the caller can correct and retry.\n *\n * @group Primitive Validation\n */\nexport const E_NO_READER_RESOLVER = createException<[string]>(\n  'E_NO_READER_RESOLVER',\n  'No reader resolver registered for tag \"%s\". Register one (with its live store binding) before decoding — see the @nhtio/adk/batteries/encoding battery.',\n  'E_NO_READER_RESOLVER',\n  422,\n  false\n)\n\n/**\n * Thrown by {@link @nhtio/adk!Tokenizable} when a DYNAMIC (evaluatable) value's evaluator function fails to\n * produce a usable string at resolve time — either it THREW, or it RETURNED A NON-STRING.\n *\n * @remarks\n * An evaluatable Tokenizable wraps a `(ctx?) => string` that is invoked at prompt-assembly time (and, with\n * no context, at measurement/serialization time). Both failure modes are PROGRAMMER errors, not recoverable\n * runtime conditions: an evaluator that throws is buggy, and a non-string return would otherwise coerce\n * silent garbage into the prompt (`undefined` → \"undefined\", an object → \"[object Object]\"). So we surface\n * loudly rather than degrade — the only sanctioned fallback is the evaluator's OWN `ctx === undefined`\n * branch, which must itself return a string. Inside a runner the throw rides the nack → error seam (a\n * dispatch error / banner); outside a runner it propagates as the real bug it is.\n *\n * The single printf argument describes the failure (\"threw\" or \"returned a non-string (`type`)\"); the\n * original error, when the evaluator threw, is attached on `cause`.\n *\n * @group Primitive Validation\n */\nexport const E_TOKENIZABLE_EVALUATOR_INVALID = createException<[string]>(\n  'E_TOKENIZABLE_EVALUATOR_INVALID',\n  'A dynamic Tokenizable evaluator did not produce a string: %s. The evaluator must return a string for every input (including when the context is undefined), and must not throw.',\n  'E_TOKENIZABLE_EVALUATOR_INVALID',\n  500,\n  true\n)\n","/**\n * Well-known `Symbol.for()` keys for the `@nhtio/encoder` custom-class contract.\n *\n * @remarks\n * A primitive opts in to `encode()`/`decode()` by implementing two symbol-keyed methods:\n *\n * - `[ENCODE_METHOD](): Encodable` — an **instance** method returning a serialisable snapshot of self.\n * - `static [DECODE_METHOD](data): T` — a **static** factory reconstructing the instance from that snapshot.\n *\n * These are the docs' \"Option B\" (zero-dependency) opt-in: because `Symbol.for()` resolves against the\n * global symbol registry by string key, a class implements the contract **without importing\n * `@nhtio/encoder`**. The encoder only enters the picture for *decoding* — `registerClass()` (shipped by\n * the `@nhtio/adk/batteries/encoding` battery) maps the wire tag back to a constructor.\n *\n * The string keys are written here exactly once. Every encodable primitive imports these constants\n * rather than re-typing the literals — a typo in one class would otherwise silently make it\n * un-encodable (the encoder would flatten the instance to a plain object instead of throwing).\n *\n * The `: unique symbol` annotation is required: TypeScript only permits a `unique symbol`-typed value\n * as a computed class-member name.\n */\n\n/** Instance method key: serialise the instance into an `Encodable` snapshot. */\nexport const ENCODE_METHOD: unique symbol = Symbol.for('@nhtio/encoder:toEncoded')\n\n/** Static method key: reconstruct an instance from an `Encodable` snapshot. */\nexport const DECODE_METHOD: unique symbol = Symbol.for('@nhtio/encoder:fromEncoded')\n","import { isInstanceOf } from './guards'\nimport type { TokenEncoding } from '../classes/tokenizable'\n\n/**\n * Ambient channel that lets a leaf token estimator ({@link @nhtio/adk!Tokenizable.estimateTokens} and the\n * primitives that delegate to it) discover whether it is running inside a runner execution — and, if so,\n * surface a non-fatal warning instead of throwing.\n *\n * @remarks\n * **Why this exists.** `estimateTokens(encoding)` takes only an encoding — it is never handed the\n * {@link @nhtio/adk!DispatchContext}. JavaScript closures are lexical, so the runner's context (a\n * different module) is NOT in scope inside the estimator; the estimator cannot check it directly. The\n * behavioural contract we need is:\n *\n * - **inside a TurnRunner run or DispatchRunner dispatch** — a token-estimation failure must DEGRADE to a\n *   cheap char-based guesstimate AND emit a `warning` (never kill the turn/dispatch);\n * - **outside those executions** — FAIL LOUD (throw), because a genuine encoder failure in non-runner code\n *   is a real bug that must surface.\n *\n * A runner publishes its warn-emit capability here for the duration of its run; the estimator reads\n * {@link currentEstimationWarnEmitter} in its catch — present ⇒ degrade + warn, absent ⇒ throw. The\n * ambient scope IS the definition of \"am I in a runner execution?\".\n *\n * **Stack, not a single slot.** `DispatchRunner.dispatch()` is a public entry point called both standalone\n * AND nested inside `TurnRunner.run()`. A LIFO stack means the innermost active runner wins: a dispatch\n * running inside a turn pushes on top of the turn's emitter, so estimations during the dispatch route to\n * the (richer, dispatch-scoped) emitter, and the turn's is restored when the dispatch returns. \"Prefer the\n * dispatch channel when both are active\" is the stack order, not a special case.\n *\n * **Synchronous by design.** Token estimation is synchronous, so the emitter on top of the stack is always\n * the one for the currently-executing estimation. {@link runWithEstimationWarnings} still restores the\n * stack in a `finally`, so an async runner body that awaits (with no synchronous estimation crossing the\n * await) remains correct: the push/pop bracket the whole body. No `async_hooks` — this runs in the browser\n * bundle too.\n */\nexport interface EstimationWarning {\n  /** The encoding whose real tokenizer failed, triggering the degrade. */\n  encoding: TokenEncoding\n  /** The underlying error thrown by the encoder (surfaced for diagnostics). */\n  error: unknown\n  /** A short, bounded preview of the text being estimated — never the full value. */\n  textPreview: string\n}\n\n/** Sink invoked by the estimator when it degrades inside a runner. */\nexport type EstimationWarnEmitter = (warning: EstimationWarning) => void\n\n// Module-level LIFO of active warn-emit sinks. Empty ⇒ no runner execution is active ⇒ estimators throw.\nconst stack: EstimationWarnEmitter[] = []\n\n/**\n * Run `body` with `emit` published as the active estimation warn-sink, restoring the previous state\n * afterwards. Runners bracket their whole run/dispatch in this so any token estimation performed within\n * (in an executor, a pipeline, a gate) can degrade-and-warn instead of throwing.\n *\n * @param emit - Sink the leaf estimator calls when it degrades; the runner forwards it to its `warning` bus.\n * @param body - The runner's work. May be sync or return a Promise; the sink stays active until it settles.\n * @returns Whatever `body` returns (including a Promise, which is awaited so the `finally` pops after it).\n */\nexport function runWithEstimationWarnings<T>(emit: EstimationWarnEmitter, body: () => T): T {\n  stack.push(emit)\n  let popped = false\n  const pop = (): void => {\n    if (popped) return\n    popped = true\n    // Pop OUR entry specifically (by identity) rather than blindly truncating, so a misuse elsewhere\n    // cannot desynchronise the stack.\n    const idx = stack.lastIndexOf(emit)\n    if (idx !== -1) stack.splice(idx, 1)\n  }\n  try {\n    const result = body()\n    // Cross-realm-safe Promise check (bare `instanceof Promise` is fragile across realms — see\n    // CONTRIBUTING §Class identity guards). Runner bodies are async, so this is the live path.\n    if (isInstanceOf<Promise<unknown>>(result, 'Promise', Promise)) {\n      // Keep the sink active until the async body settles, then pop regardless of outcome.\n      return result.finally(pop) as unknown as T\n    }\n    pop()\n    return result\n  } catch (err) {\n    pop()\n    throw err\n  }\n}\n\n/**\n * The warn-sink for the innermost active runner execution, or `undefined` when none is active. A leaf\n * estimator reads this in its catch: `undefined` is the signal to THROW (outside any runner); a defined\n * sink is the signal to emit a warning and return the char-based guesstimate.\n */\nexport function currentEstimationWarnEmitter(): EstimationWarnEmitter | undefined {\n  return stack.length > 0 ? stack[stack.length - 1] : undefined\n}\n","import { getEncoding } from 'js-tiktoken'\nimport { validator } from '@nhtio/validation'\nimport { LlamaTokenizer } from 'llama-tokenizer-js'\nimport { createException } from '../utils/exceptions'\nimport { isInstanceOf, isError } from '../utils/guards'\nimport { ENCODE_METHOD, DECODE_METHOD } from '../utils/encoder_symbols'\nimport { E_TOKENIZABLE_EVALUATOR_INVALID } from '../exceptions/runtime'\nimport { currentEstimationWarnEmitter } from '../utils/estimation_context'\nimport { fromPreTrained as geminiFromPreTrained } from '@lenml/tokenizer-gemini'\nimport type { Tiktoken } from 'js-tiktoken'\nimport type { AdkEncodableSnapshot } from './encodable'\nimport type { DispatchContext } from '../contracts/dispatch_context'\n\n/**\n * A DYNAMIC Tokenizable value: a function evaluated at prompt-ASSEMBLY time with the live dispatch\n * context, so the wrapped content computes itself coherent with the dispatch it ships in (e.g. a\n * citation instruction that adapts to whether the answer tool survived the subtractive-pass shed).\n *\n * @remarks\n * The context is OPTIONAL: the same Tokenizable is also read outside any dispatch (token measurement,\n * serialization, plain string coercion). The evaluator MUST therefore handle `ctx === undefined` and\n * return a string for EVERY input — that no-ctx branch IS its fallback. It must never throw and must\n * never return a non-string; either violation raises {@link @nhtio/adk!E_TOKENIZABLE_EVALUATOR_INVALID}\n * (loud — a mis-authored evaluator must not silently coerce garbage into the prompt). Keep evaluators\n * serializer-friendly (capture only module-level refs or values passed as explicit bindings, NOT live\n * per-turn state) so a dynamic Tokenizable round-trips its evaluator and stays dynamic across encode/decode.\n */\nexport type TokenizableEvaluator = (ctx?: DispatchContext) => string\n\n/**\n * The set of supported token encoding identifiers.\n *\n * @remarks\n * Each value maps to a specific estimation backend:\n * - `gpt2`, `r50k_base`, `p50k_base`, `p50k_edit`, `cl100k_base`, `o200k_base` — exact counts\n *   via `js-tiktoken` (OpenAI / tiktoken-compatible models).\n * - `gemini` — exact counts via `@lenml/tokenizer-gemini`, which embeds Gemini's actual\n *   SentencePiece vocabulary locally with no API call required.\n * - `gemma` — exact counts for Google's Gemma models (Gemma 2/3/4, incl. the on-device\n *   `.litertlm` / ONNX builds). Backed by the SAME `@lenml/tokenizer-gemini` package, whose bundled\n *   `tokenizer_config.json` declares `\"tokenizer_class\": \"GemmaTokenizer\"` over the shared 256k-vocab\n *   SentencePiece tokenizer — Gemini and Gemma share it, and it encodes Gemma's control tokens\n *   (`<start_of_turn>`, `<end_of_turn>`, `<eos>`, …) as single ids. Deliberate reuse, not a proxy: no\n *   extra dependency. Distinct identifier so callers can say what model they mean.\n * - `llama2` — exact counts via `llama-tokenizer-js` (Llama 1 and 2). Llama 3+ uses a\n *   different vocabulary and should use the `llama3` identifier once a suitable sync backend\n *   is available.\n * - `claude` — heuristic approximation using Anthropic's published ~3.5 chars/token ratio.\n *   No local tokenizer is available for Claude 3+ models; the Anthropic SDK's\n *   `messages.countTokens()` API is the only exact path but requires a network call.\n *\n * This array is the CANONICAL, closed set of backends built into core — adding one of these\n * requires editing core (add a case to {@link Tokenizable.estimateTokens}'s internal switch). For\n * every OTHER encoding a battery or consumer wants to measure (a model-specific tokenizer core has\n * no business knowing about), call {@link registerTokenEstimator} instead — no core edit required.\n * See {@link TokenEncodingId} for the widened identifier type that accepts both.\n */\nexport const TokenEncoding = [\n  'gpt2',\n  'r50k_base',\n  'p50k_base',\n  'p50k_edit',\n  'cl100k_base',\n  'o200k_base',\n  'gemini',\n  'gemma',\n  'llama2',\n  'claude',\n] as const\n\n/**\n * Union of all recognised token encoding identifier strings.\n *\n * @remarks\n * Derived from {@link TokenEncoding} so the type and the runtime array stay in sync\n * automatically when new encodings are added.\n */\nexport type TokenEncoding = (typeof TokenEncoding)[number]\n\n/**\n * A recognised token-encoding identifier: one of the closed {@link TokenEncoding} built-ins, OR any\n * other string registered via {@link registerTokenEstimator}.\n *\n * @remarks\n * The `(string & {})` half of the union is a widening trick, not a real intersection — `string & {}`\n * has no members beyond `string`, so it accepts any string value while `TokenEncoding` still\n * contributes its literal members to editor autocomplete (a bare `string` union member would erase\n * that autocomplete entirely, since TypeScript collapses `TokenEncoding | string` to `string`). Use\n * this type wherever an API accepts \"a built-in encoding, or a custom one\" — including the `tokenEncoding`\n * property on battery adapter options, which treat the built-ins as suggestions but permit any string.\n */\nexport type TokenEncodingId = TokenEncoding | (string & {})\n\n/**\n * A custom token-count function registered for a non-built-in {@link TokenEncodingId} via\n * {@link registerTokenEstimator}.\n *\n * @remarks\n * Synchronous, matching the built-in estimation backends: every backend behind the\n * {@link TokenEncoding} switch (`js-tiktoken`, `@lenml/tokenizer-gemini`, `llama-tokenizer-js`, the\n * Claude heuristic) resolves synchronously, and {@link Tokenizable.estimateTokens} itself returns a\n * plain `number` — not a `Promise<number>`. A custom estimator therefore must not be async either, so\n * a registered encoding stays a drop-in peer of the built-ins (same call shape, no `await` threaded\n * through `estimateTokens` for some encodings and not others). Wrap an inherently-async tokenizer in a\n * synchronous cache (measure ahead of time / memoize a warmed instance) before registering it.\n *\n * @param value - The already-RESOLVED text to count (the same string `countFor` measures for the\n *   built-in backends — i.e. `render(ctx)`'s output, never the raw evaluator or ctx).\n * @returns The estimated token count for `value`.\n */\nexport type TokenEstimatorFn = (value: string) => number\n\n/**\n * Thrown by {@link registerTokenEstimator} when the given encoding identifier names a built-in\n * {@link TokenEncoding} rather than a genuinely custom one.\n *\n * @remarks\n * The built-in encodings are canonical: `'gemma'`, `'cl100k_base'`, and friends must always resolve\n * to their core backend (`js-tiktoken`, `@lenml/tokenizer-gemini`, `llama-tokenizer-js`, the Claude\n * heuristic), never to a consumer-supplied override. Allowing a shadow registration would let one\n * battery silently change another's token counts for a shared built-in name — a correctness hazard\n * that is cheap to prevent at registration time. Fatal: this is a programming error in the caller\n * (pick a distinct identifier), not a runtime condition to recover from.\n */\nexport const E_TOKEN_ESTIMATOR_SHADOWS_BUILTIN = createException<[string]>(\n  'E_TOKEN_ESTIMATOR_SHADOWS_BUILTIN',\n  'Cannot register a token estimator for \"%s\": it shadows a built-in TokenEncoding. Built-in encodings always resolve to their core backend and cannot be overridden — register a distinct encoding identifier instead.',\n  'E_TOKEN_ESTIMATOR_SHADOWS_BUILTIN',\n  409,\n  true\n)\n\n// Custom encodings registered via registerTokenEstimator, consulted AFTER the built-in switch so the\n// closed set's fast path (and its degrade-vs-throw contract) is never disturbed by registration.\nconst customEstimators = new Map<string, TokenEstimatorFn>()\nconst warnedUnregisteredEncodings = new Set<string>()\n\n// The built-in identifiers as a Set for O(1) shadow-checks and the isBuiltinEncoding guard below.\nconst builtinEncodingSet = new Set<string>(TokenEncoding)\n\n/** Narrows a {@link TokenEncodingId} to the closed {@link TokenEncoding} union when it names a built-in. */\nconst isBuiltinEncoding = (encoding: string): encoding is TokenEncoding =>\n  builtinEncodingSet.has(encoding)\n\n/**\n * Register (or replace) a {@link TokenEstimatorFn} for a custom {@link TokenEncodingId}, so\n * {@link Tokenizable.estimateTokens} can measure it without a core code change.\n *\n * @remarks\n * This is the additive escape hatch for the closed {@link TokenEncoding} set. Say a context-management\n * battery needs to measure tokens for a model that core has no built-in backend for — it simply calls\n * this once, at startup, for that model's identifier. From then on the encoding is measurable, with no\n * core code change (a new case in {@link Tokenizable.estimateTokens}'s switch) ever required. Mirrors the\n * {@link @nhtio/adk!registerMediaReaderResolver} / {@link @nhtio/adk!registerSpoolReaderResolver} registry\n * idiom used for reader handles — register a factory once, core (or the primitive) consults it, nobody\n * imports a battery from core.\n *\n * Resolution order inside {@link Tokenizable.estimateTokens}: the built-in switch is tried FIRST (so\n * the closed set's fast path — including its degrade-to-heuristic-on-encoder-failure contract — is\n * completely unaffected by the registry existing), and only an encoding the switch doesn't recognise\n * falls through to this registry.\n *\n * Idempotent-by-overwrite: registering the same `encoding` twice replaces the previous estimator —\n * useful for hot-swapping a warmed tokenizer instance without restarting. Registering a name that\n * shadows a BUILT-IN {@link TokenEncoding} (e.g. `'gemma'`, `'cl100k_base'`) is rejected: the built-ins\n * are canonical and must always resolve to their core backend, never to a consumer override.\n *\n * @param encoding - The custom encoding identifier this estimator handles. Must not be one of the\n *   built-in {@link TokenEncoding} values.\n * @param estimator - The synchronous token-count function to call for `encoding`.\n * @throws {@link @nhtio/adk!E_TOKEN_ESTIMATOR_SHADOWS_BUILTIN} when `encoding` names a built-in.\n */\nexport function registerTokenEstimator(encoding: string, estimator: TokenEstimatorFn): void {\n  if (isBuiltinEncoding(encoding)) {\n    throw new E_TOKEN_ESTIMATOR_SHADOWS_BUILTIN([encoding])\n  }\n  customEstimators.set(encoding, estimator)\n}\n\n/**\n * Backing schema for {@link Tokenizable.schema}.\n *\n * @remarks\n * Accepts a plain `string` or an existing {@link Tokenizable} instance. Strings pass through\n * unchanged; {@link Tokenizable} instances are accepted via {@link Tokenizable.isTokenizable}\n * to remain cross-realm safe.\n */\nconst stringOrTokenizableSchema = validator.alternatives(\n  validator.string(),\n  validator.custom((value, helpers) => {\n    if (Tokenizable.isTokenizable(value)) {\n      return value\n    }\n    return helpers.error('any.invalid')\n  })\n)\n\n/**\n * Backing schema for {@link Tokenizable.emptyableSchema}.\n *\n * @remarks\n * Identical to {@link stringOrTokenizableSchema} except that the EMPTY string is accepted. Joi\n * strings disallow `''` by default, so the strict fragment rejects it while a `new Tokenizable('')`\n * instance sails through the custom branch — an inconsistency that only shows up once a caller\n * legitimately has nothing to put in the field.\n *\n * Deliberately a SEPARATE fragment rather than relaxing the strict one: `Tokenizable.schema` also\n * backs `systemPrompt`, `standingInstructions`, `Identity.representation`, and `Memory.content`,\n * where an empty value is meaningless and should stay a validation error. Opt in per-field.\n */\nconst emptyableStringOrTokenizableSchema = validator.alternatives(\n  validator.string().allow(''),\n  validator.custom((value, helpers) => {\n    if (Tokenizable.isTokenizable(value)) {\n      return value\n    }\n    return helpers.error('any.invalid')\n  })\n)\n\n// Lazily-initialised singletons — tokenizers are expensive to load so we defer\n// until first use and reuse across all Tokenizable instances thereafter.\nlet geminiTokenizerInstance: ReturnType<typeof geminiFromPreTrained> | undefined\nlet llamaTokenizerInstance: InstanceType<typeof LlamaTokenizer> | undefined\n\n// js-tiktoken's `getEncoding` has no internal cache — each call does `new Tiktoken(<ranks>)`,\n// parsing the full BPE rank table (~800ms for o200k_base). Building the encoder dwarfs the\n// subsequent `encode()` (~0.6ms) by ~1000×, so a fresh encoder per `estimateTokens` call turns\n// repeated counting (e.g. re-measuring an accumulating dispatch context every iteration) into\n// O(iterations) encoder rebuilds that monopolise a single-threaded host. Cache the encoder per\n// encoding, mirroring the Gemini/Llama singletons above — Tiktoken instances are stateless and\n// safe to reuse across all Tokenizable instances.\nconst tiktokenEncoderInstances = new Map<TokenEncoding, Tiktoken>()\n\nconst getGeminiTokenizer = () => {\n  if (!geminiTokenizerInstance) {\n    geminiTokenizerInstance = geminiFromPreTrained()\n  }\n  return geminiTokenizerInstance\n}\n\nconst getLlamaTokenizer = () => {\n  if (!llamaTokenizerInstance) {\n    llamaTokenizerInstance = new LlamaTokenizer()\n  }\n  return llamaTokenizerInstance\n}\n\nconst getTiktokenEncoder = (encoding: TokenEncoding): Tiktoken => {\n  let enc = tiktokenEncoderInstances.get(encoding)\n  if (!enc) {\n    enc = getEncoding(encoding as any)\n    tiktokenEncoderInstances.set(encoding, enc)\n  }\n  return enc\n}\n\n/**\n * A mutable string with a built-in token counter.\n *\n * @remarks\n * The wrapped string can be read via the standard coercion protocol and updated at any time via\n * {@link Tokenizable.set}. Token counts are computed lazily on first access per encoding and\n * cached until the value changes, avoiding redundant encoder invocations when the same content\n * is measured multiple times across a pipeline.\n *\n * Estimation is dispatched by encoding identifier — see {@link TokenEncoding} for the full list of\n * built-in backends and their accuracy characteristics, and {@link registerTokenEstimator} for adding\n * more without a core change. An encoding that is neither a built-in nor registered resolves to\n * `undefined` (see {@link Tokenizable.estimateTokens}) — this pre-dates the registry and is unchanged\n * by it. Separately, a built-in encoder that THROWS while measuring (as opposed to an unrecognised\n * name) degrades to a `ceil(length / 3.5)` character heuristic inside a runner execution — see\n * `degradeOrThrow` and `utils/estimation_context`.\n *\n * The class implements the standard JS value-coercion protocol (`toString`, `valueOf`,\n * `toJSON`, `toLocaleString`, `Symbol.for('nodejs.util.inspect.custom')`) so instances behave\n * transparently as strings in most contexts.\n */\nexport class Tokenizable {\n  /** The set of supported token-encoding identifiers, re-exposed as a static for convenience. */\n  public static TokenEncoding = TokenEncoding\n\n  /**\n   * Validator schema that accepts a plain `string` or a {@link Tokenizable} instance.\n   *\n   * @remarks\n   * Reusable fragment for any schema that wants to accept either form — for example,\n   * `systemPrompt` and each item in `standingInstructions` in `turnContextSchema`.\n   */\n  public static schema = stringOrTokenizableSchema\n\n  /**\n   * Variant of {@link Tokenizable.schema} that additionally accepts the EMPTY string.\n   *\n   * @remarks\n   * For fields where \"present but empty\" is a legitimate state rather than a mistake — e.g.\n   * {@link @nhtio/adk!Thought.content} in opaque-replay mode, where the meaning lives in the vendor\n   * `payload` and the prose is only kept for token-accounting and observer inspection.\n   *\n   * Do NOT reach for this by default. {@link Tokenizable.schema} stays strict precisely because an\n   * empty system prompt or a blank standing instruction is a bug worth failing on.\n   */\n  public static emptyableSchema = emptyableStringOrTokenizableSchema\n\n  declare toJSON: () => string\n  declare toString: () => string\n  declare valueOf: () => string\n  declare toLocaleString: () => string\n  /** Replace the wrapped value (string or evaluator) and invalidate the cached token estimates. */\n  declare set: (value: string | TokenizableEvaluator) => void\n  /**\n   * Resolve the wrapped content against an OPTIONAL dispatch context and return the string. For a static\n   * value the context is ignored. For a dynamic (evaluatable) value the evaluator is invoked with `ctx`\n   * ({@link TokenizableEvaluator}); assembly passes the live context so the content matches the dispatch\n   * it ships in, while a no-context call returns the evaluator's `undefined`-branch fallback.\n   */\n  /** Whether the current wrapped value is evaluator-backed rather than a static string. */\n  declare readonly dynamic: boolean\n  /** Resolve the value against an optional dispatch context. */\n  declare render: (ctx?: DispatchContext) => string\n  /**\n   * Estimate the token count under the given {@link TokenEncodingId} of the string this Tokenizable\n   * resolves to for the OPTIONAL context — i.e. of `render(ctx)`. Passing the same `ctx` assembly uses\n   * keeps the budget count honest for dynamic content (it measures exactly what will ship). Accepts\n   * both a built-in {@link TokenEncoding} and any encoding registered via {@link registerTokenEstimator}.\n   */\n  declare estimateTokens: (encoding: TokenEncodingId, ctx?: DispatchContext) => number\n\n  // Exactly one of these is set. A static value keeps `#value`; a dynamic value keeps `#evaluator`\n  // (and `#value` stays the empty string, never read on the dynamic path).\n  #value: string\n  #evaluator: TokenizableEvaluator | undefined\n  // Per-encoding cache for the STATIC string and the no-ctx (fallback) resolution — both stable.\n  #cache: Map<TokenEncodingId, number> = new Map()\n  // Per-context cache for DYNAMIC + ctx resolutions: WeakMap<ctxObject, Map<encoding, count>>. A dynamic\n  // value resolves differently per ctx, so a single number can't be cached; keying by the ctx object\n  // reuses the count across the several measures of one dispatch (subtractive pass + overflow guard) and\n  // auto-frees when the ctx is garbage-collected. (Same ctx object ⇒ same resolved string within a\n  // dispatch, since the evaluator is a pure read of that ctx's state.)\n  #ctxCache: WeakMap<object, Map<TokenEncodingId, number>> = new WeakMap()\n\n  /**\n   * @param value - The initial value to wrap: a plain `string` (static) or a {@link TokenizableEvaluator}\n   *   evaluated at assembly time (dynamic).\n   */\n  constructor(value: string | TokenizableEvaluator) {\n    const isFn = typeof value === 'function'\n    this.#evaluator = isFn ? (value as TokenizableEvaluator) : undefined\n    this.#value = isFn ? '' : (value as string)\n\n    // Resolve the wrapped content to a string for an OPTIONAL context. Static → the stored string.\n    // Dynamic → invoke the evaluator; a throw OR a non-string return is a programmer bug → raise\n    // E_TOKENIZABLE_EVALUATOR_INVALID (loud, no silent coercion, no degrade). The evaluator's own\n    // `ctx === undefined` branch is the only sanctioned fallback and must itself return a string.\n    const resolve = (ctx?: DispatchContext): string => {\n      const fn = this.#evaluator\n      if (!fn) return this.#value\n      let result: string\n      try {\n        result = fn(ctx)\n      } catch (err) {\n        throw new E_TOKENIZABLE_EVALUATOR_INVALID(['the evaluator threw'], {\n          cause: isError(err) ? err : new Error(String(err)),\n        })\n      }\n      if (typeof result !== 'string') {\n        throw new E_TOKENIZABLE_EVALUATOR_INVALID([`returned a non-string (${typeof result})`])\n      }\n      return result\n    }\n\n    // Raw, dependency-free token estimate (~3.5 chars/token) of the RESOLVED text. No encoder, no\n    // special-token rules, effectively cannot throw — the guesstimate a real tokenizer degrades TO.\n    const estimateTokensRaw = (text: string): number => Math.ceil(text.length / 3.5)\n\n    // Shared failure policy for the real tokenizers, enforcing the degrade-vs-throw CONTRACT:\n    //   - inside a TurnRunner run / DispatchRunner dispatch (an estimation warn-sink is on the ambient\n    //     stack) → emit a `warning` and DEGRADE to the raw guesstimate, so a token-estimation failure\n    //     NEVER kills the turn/dispatch;\n    //   - outside any runner (no sink) → RE-THROW, because a genuine encoder failure in non-runner code is\n    //     a real bug that must surface (loud), not be silently papered over.\n    // This replaces the former `catch → Number.POSITIVE_INFINITY`, which — with the armed overflow guards —\n    // made `Infinity > contextWindow` spuriously trip `E_*_CONTEXT_OVERFLOW` on, e.g., text containing a\n    // special token. See utils/estimation_context.\n    const degradeOrThrow = (encoding: TokenEncoding, text: string, error: unknown): number => {\n      const emit = currentEstimationWarnEmitter()\n      if (!emit) throw error\n      emit({ encoding, error, textPreview: text.slice(0, 80) })\n      return estimateTokensRaw(text)\n    }\n\n    const estimateTokensWithTiktoken = (encoding: TokenEncoding, text: string): number => {\n      try {\n        const enc: Tiktoken = getTiktokenEncoder(encoding)\n        // `encode(text, allowedSpecial, disallowedSpecial)`. js-tiktoken DEFAULTS `disallowedSpecial` to\n        // \"all\", so any registered special-token substring in the text (e.g. a doc that mentions\n        // `<|endoftext|>`, or model output echoing `<|im_start|>`) makes `encode` THROW\n        // (\"The text contains a special token that is not allowed\"). We are ESTIMATING a token count, not\n        // round-tripping through the model, so a special-token literal must be counted as ordinary text,\n        // never rejected. Pass `disallowedSpecial: []` to disable the guard: specials are BPE-encoded as\n        // plain text. Any OTHER encoder failure follows the degrade-vs-throw contract (degradeOrThrow).\n        return enc.encode(text, [], []).length\n      } catch (err) {\n        return degradeOrThrow(encoding, text, err)\n      }\n    }\n\n    const estimateTokensWithGemini = (text: string): number => {\n      try {\n        return getGeminiTokenizer().encode(text).length\n      } catch (err) {\n        return degradeOrThrow('gemini', text, err)\n      }\n    }\n\n    // Gemma reuses the very same tokenizer: `@lenml/tokenizer-gemini` bundles the shared 256k-vocab\n    // SentencePiece tokenizer whose config is `\"tokenizer_class\": \"GemmaTokenizer\"`. Kept as its own\n    // function (rather than folding 'gemma' into the gemini case) so the intent is explicit and a future\n    // swap to a dedicated Gemma package is a one-line change here.\n    const estimateTokensWithGemma = (text: string): number => {\n      try {\n        return getGeminiTokenizer().encode(text).length\n      } catch (err) {\n        return degradeOrThrow('gemma', text, err)\n      }\n    }\n\n    const estimateTokensWithLlama2 = (text: string): number => {\n      try {\n        return getLlamaTokenizer().encode(text, false).length\n      } catch (err) {\n        return degradeOrThrow('llama2', text, err)\n      }\n    }\n\n    const estimateTokensWithClaudeHeuristic = (text: string): number => estimateTokensRaw(text)\n\n    // Count tokens of an already-RESOLVED string under one of the CLOSED built-in encodings (the\n    // switch shared by all built-in callers). Unchanged fast path — `countFor` below only reaches this\n    // once it has already narrowed `encoding` to a real {@link TokenEncoding} member.\n    const countForBuiltin = (encoding: TokenEncoding, text: string): number => {\n      switch (encoding) {\n        case 'gpt2':\n        case 'r50k_base':\n        case 'p50k_base':\n        case 'p50k_edit':\n        case 'cl100k_base':\n        case 'o200k_base':\n          return estimateTokensWithTiktoken(encoding, text)\n        case 'gemini':\n          return estimateTokensWithGemini(text)\n        case 'gemma':\n          return estimateTokensWithGemma(text)\n        case 'llama2':\n          return estimateTokensWithLlama2(text)\n        case 'claude':\n          return estimateTokensWithClaudeHeuristic(text)\n      }\n    }\n\n    // Count tokens of an already-RESOLVED string under any recognised {@link TokenEncodingId}.\n    // Resolution order: (1) the built-in switch — completely unchanged, so the closed set's fast path\n    // and degrade-vs-throw contract are untouched by the registry existing; (2) the custom-estimator\n    // registry, for anything {@link registerTokenEstimator} has registered; (3) the pre-existing\n    // fallback path for a truly unrecognised encoding (emits a warning and falls back to the safe\n    // 3.5 chars/token heuristic, ensuring overflow math always gets a finite upper-bound estimate).\n    const countFor = (encoding: TokenEncodingId, text: string): number => {\n      if (isBuiltinEncoding(encoding)) {\n        return countForBuiltin(encoding, text)\n      }\n      const custom = customEstimators.get(encoding)\n      if (custom) {\n        return custom(text)\n      }\n      // Unrecognised AND unregistered encodings use the generic character heuristic. Warn once per\n      // encoding so callers know the estimate is uncalibrated, while preserving a finite count for\n      // context-window arithmetic.\n      if (!warnedUnregisteredEncodings.has(encoding)) {\n        warnedUnregisteredEncodings.add(encoding)\n        console.warn(\n          `No token estimator is registered for \"${encoding}\"; using the uncalibrated character heuristic.`\n        )\n      }\n      return text.length\n    }\n\n    // The standard coercion protocol takes NO argument, so it resolves with no context → the static\n    // string, or (dynamic) the evaluator's `undefined`-branch fallback. `render(ctx)` is the explicit,\n    // context-aware read that prompt assembly uses.\n    const coerce = (): string => resolve(undefined)\n\n    Object.defineProperties(this, {\n      toJSON: {\n        value: coerce,\n        enumerable: false,\n        configurable: false,\n        writable: false,\n      },\n      toString: {\n        value: coerce,\n        enumerable: false,\n        configurable: false,\n        writable: false,\n      },\n      valueOf: {\n        value: coerce,\n        enumerable: false,\n        configurable: false,\n        writable: false,\n      },\n      toLocaleString: {\n        value: coerce,\n        enumerable: false,\n        configurable: false,\n        writable: false,\n      },\n      [Symbol.for('nodejs.util.inspect.custom')]: {\n        value: coerce,\n        enumerable: false,\n        configurable: false,\n        writable: false,\n      },\n      dynamic: {\n        get: () => this.#evaluator !== undefined,\n        enumerable: true,\n        configurable: false,\n      },\n      render: {\n        value: (ctx?: DispatchContext): string => resolve(ctx),\n        enumerable: false,\n        configurable: false,\n        writable: false,\n      },\n      set: {\n        value: (next: string | TokenizableEvaluator) => {\n          const nextIsFn = typeof next === 'function'\n          this.#evaluator = nextIsFn ? (next as TokenizableEvaluator) : undefined\n          this.#value = nextIsFn ? '' : (next as string)\n          this.#cache.clear()\n          this.#ctxCache = new WeakMap()\n        },\n        enumerable: false,\n        configurable: false,\n        writable: false,\n      },\n      estimateTokens: {\n        value: (encoding: TokenEncodingId, ctx?: DispatchContext): number => {\n          // Cache selection: a STATIC value (or a no-ctx resolution — the stable fallback) uses the\n          // per-encoding Map; a DYNAMIC value WITH a ctx uses the per-ctx WeakMap (the resolved string\n          // varies by ctx, so a single number can't be shared). `ctx === undefined` always hits the\n          // stable per-encoding cache regardless of static/dynamic.\n          const useCtxCache = this.#evaluator !== undefined && ctx !== undefined\n          if (useCtxCache) {\n            let m = this.#ctxCache.get(ctx as unknown as object)\n            if (m?.has(encoding)) return m.get(encoding)!\n            const text = resolve(ctx)\n            const est = countFor(encoding, text)\n            if (!m) {\n              m = new Map()\n              this.#ctxCache.set(ctx as unknown as object, m)\n            }\n            m.set(encoding, est)\n            return est\n          }\n          if (this.#cache.has(encoding)) {\n            return this.#cache.get(encoding)!\n          }\n          const text = resolve(undefined)\n          const estimate = countFor(encoding, text)\n          this.#cache.set(encoding, estimate)\n          return estimate\n        },\n        enumerable: false,\n        configurable: false,\n        writable: false,\n      },\n    })\n  }\n\n  /**\n   * Convenience overload for one-off token counting without managing a {@link Tokenizable} instance.\n   *\n   * @remarks\n   * Creates a temporary instance and immediately discards it — no caching benefit. Use the\n   * instance method when you need to count the same value under multiple encodings or when the\n   * value may change over time.\n   *\n   * @param value - The string (or {@link TokenizableEvaluator}) to count tokens for.\n   * @param encoding - The encoding identifier to use for counting — a built-in {@link TokenEncoding} or\n   *   any encoding registered via {@link registerTokenEstimator}.\n   * @param ctx - Optional dispatch context; for a dynamic value it selects which resolved string is\n   *   counted (so the count matches what assembly ships). Ignored for a static string.\n   * @returns The estimated number of tokens.\n   */\n  public static estimateTokens(\n    value: string | TokenizableEvaluator,\n    encoding: TokenEncodingId,\n    ctx?: DispatchContext\n  ): number {\n    const temp = new Tokenizable(value)\n    return temp.estimateTokens(encoding, ctx)\n  }\n\n  /**\n   * Returns `true` if `value` is a {@link Tokenizable} 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 Tokenizable} instance.\n   */\n  public static isTokenizable(value: unknown): value is Tokenizable {\n    return isInstanceOf(value, 'Tokenizable', Tokenizable)\n  }\n\n  /**\n   * Serialise this Tokenizable into an `@nhtio/encoder` snapshot.\n   *\n   * @remarks\n   * The wrapped VALUE is the entire state; the token-count caches are derived and deliberately not encoded\n   * (they rebuild lazily after decode). For a STATIC value the snapshot is the string. For a DYNAMIC value\n   * the snapshot is the EVALUATOR FUNCTION itself — `@nhtio/encoder` serialises functions (source +\n   * explicit bindings), so a dynamic Tokenizable round-trips its evaluator and stays dynamic, re-evaluating\n   * live on the next assembly (it does NOT downgrade to a frozen string). Evaluators must therefore stay\n   * serializer-friendly: capture only module-level refs / explicit bindings, not live per-turn state.\n   * Round-trips via {@link Tokenizable.[DECODE_METHOD]}.\n   *\n   * @returns The wrapped string, or the evaluator function for a dynamic value.\n   */\n  [ENCODE_METHOD](): AdkEncodableSnapshot {\n    return this.#evaluator ?? this.#value\n  }\n\n  /**\n   * Reconstruct a {@link Tokenizable} from an {@link Tokenizable.[ENCODE_METHOD]} snapshot.\n   *\n   * @param data - The wrapped string (static) or evaluator function (dynamic) produced by\n   *   {@link Tokenizable.[ENCODE_METHOD]}.\n   * @returns A fresh {@link Tokenizable} over the same value.\n   */\n  static [DECODE_METHOD](data: AdkEncodableSnapshot): Tokenizable {\n    return new Tokenizable(data as string | TokenizableEvaluator)\n  }\n}\n\n/**\n * Returns `true` if `value` is a {@link Tokenizable} instance.\n *\n * @remarks\n * Module-level convenience alias for {@link Tokenizable.isTokenizable}. Prefer this form when\n * you need a standalone type guard without importing the full class.\n *\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 Tokenizable} instance.\n */\nexport const isTokenizable = (value: unknown): value is Tokenizable => {\n  return isInstanceOf(value, 'Tokenizable', Tokenizable)\n}\n"],"mappings":"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"}

package/{tool_call-Cahji8ZY.mjs → tool_call-8crmZsO8.mjs}

@@ -1,9 +1,9 @@
 import { a as passesSchema, o as validateOrThrow } from "./exceptions-DRYLe-J4.mjs";
-import { A as E_NOT_A_MEDIA_READER, F as E_READER_NOT_DESCRIBABLE, f as E_INVALID_INITIAL_MEDIA_VALUE, o as DECODE_METHOD, r as Tokenizable, s as ENCODE_METHOD, v as E_INVALID_INITIAL_TOOL_CALL_VALUE } from "./tokenizable-xPXj1AQX.mjs";
 import { n as isInstanceOf, r as isObject, t as isError } from "./guards-BEpY7lBI.mjs";
-import { c as resolveMediaReader, g as Registry, t as SpooledArtifact } from "./spooled_artifact-BMtuIsu6.mjs";
-import { validator } from "@nhtio/validation";
+import { A as E_NOT_A_MEDIA_READER, F as E_READER_NOT_DESCRIBABLE, f as E_INVALID_INITIAL_MEDIA_VALUE, o as DECODE_METHOD, r as Tokenizable, s as ENCODE_METHOD, v as E_INVALID_INITIAL_TOOL_CALL_VALUE } from "./tokenizable-xPXj1AQX.mjs";
+import { c as resolveMediaReader, m as Registry, t as SpooledArtifact } from "./spooled_artifact-BkOe4-j-.mjs";
 import { v6 } from "uuid";
+import { validator } from "@nhtio/validation";
 //#region src/lib/helpers/base64.ts
 var getBuffer = () => {
 	return globalThis.Buffer;
@@ -717,4 +717,4 @@ var ToolCall = class ToolCall {
 //#endregion
 export { mediaReaderSchema as a, implementsMediaReader as i, Media as n, decodeBase64 as o, isMedia as r, encodeBase64 as s, ToolCall as t };
 
-//# sourceMappingURL=tool_call-Cahji8ZY.mjs.map
+//# sourceMappingURL=tool_call-8crmZsO8.mjs.map