@nhtio/adk 0.1.0-master-f0aa531d

package/index.mjs

@@ -0,0 +1,31 @@
+import { n as ValidationException } from "./exceptions-NrzIHw_R.mjs";
+import { a as Tokenizable, c as isObject, i as TokenEncoding, o as isError, r as Registry, s as isInstanceOf, t as ToolRegistry } from "./tool_registry-DqLOyGyG.mjs";
+import { C as E_NOT_A_SPOOL_READER, D as E_TOOL_DOWNSTREAM_ERROR, E as E_TOOL_ALREADY_REGISTERED, O as E_TURN_GATE_ABORTED, T as E_PIPELINE_SHORT_CIRCUITED, _ as E_INVALID_TURN_GATE_RESOLUTION, a as E_INVALID_INITIAL_MEMORY_VALUE, b as E_LLM_EXECUTION_EXECUTOR_ERROR, d as E_INVALID_INITIAL_TOOL_VALUE, f as E_INVALID_INITIAL_TURN_GATE_VALUE, g as E_INVALID_TURN_CONTEXT, h as E_INVALID_TOOL_ARGS, k as E_TURN_GATE_TIMEOUT, l as E_INVALID_INITIAL_THOUGHT_VALUE, m as E_INVALID_LLM_EXECUTION_CONTEXT, n as E_INPUT_PIPELINE_ERROR, o as E_INVALID_INITIAL_MESSAGE_VALUE, p as E_INVALID_LLM_DISPATCH_INPUT, r as E_INVALID_INITIAL_IDENTITY_VALUE, s as E_INVALID_INITIAL_REGISTRY_VALUE, t as E_DISPATCH_PIPELINE_ERROR, u as E_INVALID_INITIAL_TOOL_CALL_VALUE, v as E_INVALID_TURN_RUNNER_CONFIG, w as E_OUTPUT_PIPELINE_ERROR, x as E_LLM_EXECUTION_GATE_NOT_SUPPORTED, y as E_LLM_EXECUTION_ALREADY_SIGNALLED } from "./runtime-CrEPIFgr.mjs";
+import { i as Identity, n as Message, r as Memory, t as Thought } from "./thought-CDb457b4.mjs";
+import { i as Retrievable, n as fromWebFile, r as inMemoryMediaReader, t as fromFetch } from "./common-DeZaonK1.mjs";
+import { a as mediaReaderSchema, i as implementsMediaReader, n as Media, r as isMedia, t as ToolCall } from "./tool_call-BKyyxGaZ.mjs";
+import { t as Tool } from "./tool-D2WB1EA1.mjs";
+import { i as ArtifactTool, r as implementsSpoolReader, t as SpooledArtifact } from "./spooled_artifact-C5ZtGxuJ.mjs";
+import { n as SpooledJsonArtifact, t as SpooledMarkdownArtifact } from "./spooled_markdown_artifact-BpUJol0W.mjs";
+import { t as DispatchRunner } from "./dispatch_runner-9j6bXHL3.mjs";
+import "./dispatch_runner.mjs";
+import "./exceptions.mjs";
+import { t as TurnRunner } from "./turn_runner-y7eyEcJH.mjs";
+import { isArtifactTool, isBaseException, isDispatchContext, isDispatchRunner, isIdentity, isMemory, isMessage, isRegistry, isSpooledArtifact, isSpooledArtifactConstructor, isSpooledJsonArtifact, isSpooledMarkdownArtifact, isThought, isTokenizable, isTool, isToolCall, isToolRegistry, isTurnContext, isTurnGate, isTurnRunner } from "./guards.mjs";
+import "./turn_runner.mjs";
+//#region src/index.ts
+/**
+* Root convenience barrel for the ADK's core runtime values and public TypeScript contracts.
+*
+* @module @nhtio/adk
+*/
+/**
+* The current version of the package.
+*
+* @tip This is a constant that is replaced during the build process with the actual version of the package.
+*/
+var version = "0.1.0-master-f0aa531d";
+//#endregion
+export { ArtifactTool, DispatchRunner, E_DISPATCH_PIPELINE_ERROR, E_INPUT_PIPELINE_ERROR, E_INVALID_INITIAL_IDENTITY_VALUE, E_INVALID_INITIAL_MEMORY_VALUE, E_INVALID_INITIAL_MESSAGE_VALUE, E_INVALID_INITIAL_REGISTRY_VALUE, E_INVALID_INITIAL_THOUGHT_VALUE, E_INVALID_INITIAL_TOOL_CALL_VALUE, E_INVALID_INITIAL_TOOL_VALUE, E_INVALID_INITIAL_TURN_GATE_VALUE, E_INVALID_LLM_DISPATCH_INPUT, E_INVALID_LLM_EXECUTION_CONTEXT, E_INVALID_TOOL_ARGS, E_INVALID_TURN_CONTEXT, E_INVALID_TURN_GATE_RESOLUTION, E_INVALID_TURN_RUNNER_CONFIG, E_LLM_EXECUTION_ALREADY_SIGNALLED, E_LLM_EXECUTION_EXECUTOR_ERROR, E_LLM_EXECUTION_GATE_NOT_SUPPORTED, E_NOT_A_SPOOL_READER, E_OUTPUT_PIPELINE_ERROR, E_PIPELINE_SHORT_CIRCUITED, E_TOOL_ALREADY_REGISTERED, E_TOOL_DOWNSTREAM_ERROR, E_TURN_GATE_ABORTED, E_TURN_GATE_TIMEOUT, Identity, Media, Memory, Message, Registry, Retrievable, SpooledArtifact, SpooledJsonArtifact, SpooledMarkdownArtifact, Thought, TokenEncoding, Tokenizable, Tool, ToolCall, ToolRegistry, TurnRunner, ValidationException, fromFetch, fromWebFile, implementsMediaReader, implementsSpoolReader, inMemoryMediaReader, isArtifactTool, isBaseException, isDispatchContext, isDispatchRunner, isError, isIdentity, isInstanceOf, isMedia, isMemory, isMessage, isObject, isRegistry, isSpooledArtifact, isSpooledArtifactConstructor, isSpooledJsonArtifact, isSpooledMarkdownArtifact, isThought, isTokenizable, isTool, isToolCall, isToolRegistry, isTurnContext, isTurnGate, isTurnRunner, mediaReaderSchema, version };
+
+//# sourceMappingURL=index.mjs.map

package/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * Root convenience barrel for the ADK's core runtime values and public TypeScript contracts.\n *\n * @module @nhtio/adk\n */\n\n/**\n * The current version of the package.\n *\n * @tip This is a constant that is replaced during the build process with the actual version of the package.\n */\nexport const version = __VERSION__\n\n// ── Data primitives (value classes + Raw* types) ──────────────────────────────\n\nexport {\n  Tokenizable,\n  TokenEncoding,\n  Registry,\n  Identity,\n  Memory,\n  Message,\n  Retrievable,\n  Thought,\n  ToolCall,\n  Tool,\n  ArtifactTool,\n  ToolRegistry,\n  SpooledArtifact,\n  SpooledJsonArtifact,\n  SpooledMarkdownArtifact,\n  implementsSpoolReader,\n  Media,\n  isMedia,\n  implementsMediaReader,\n  mediaReaderSchema,\n  inMemoryMediaReader,\n  fromFetch,\n  fromWebFile,\n} from './common'\n\nexport type {\n  RawMedia,\n  SerializedMedia,\n  MediaKind,\n  MediaTrustTier,\n  MediaModalityHazard,\n  MediaStashEntry,\n  MediaReader,\n} from './common'\n\n// ── Runners (the entry points for executing turns and dispatches) ─────────────\n\nexport { TurnRunner } from './turn_runner'\nexport { DispatchRunner } from './dispatch_runner'\n\n// ── Freestanding guards ───────────────────────────────────────────────────────\n\nexport {\n  isInstanceOf,\n  isError,\n  isObject,\n  isBaseException,\n  isIdentity,\n  isMemory,\n  isMessage,\n  isRegistry,\n  isThought,\n  isTokenizable,\n  isTool,\n  isArtifactTool,\n  isToolCall,\n  isToolRegistry,\n  isTurnGate,\n  isSpooledArtifact,\n  isSpooledArtifactConstructor,\n  isSpooledJsonArtifact,\n  isSpooledMarkdownArtifact,\n  isTurnContext,\n  isTurnRunner,\n  isDispatchContext,\n  isDispatchRunner,\n} from './guards'\n\n// ── Exceptions ────────────────────────────────────────────────────────────────\n\nexport {\n  ValidationException,\n  E_INVALID_TURN_RUNNER_CONFIG,\n  E_INVALID_TURN_CONTEXT,\n  E_INPUT_PIPELINE_ERROR,\n  E_OUTPUT_PIPELINE_ERROR,\n  E_PIPELINE_SHORT_CIRCUITED,\n  E_INVALID_INITIAL_REGISTRY_VALUE,\n  E_INVALID_INITIAL_MEMORY_VALUE,\n  E_INVALID_INITIAL_MESSAGE_VALUE,\n  E_INVALID_INITIAL_IDENTITY_VALUE,\n  E_INVALID_INITIAL_THOUGHT_VALUE,\n  E_INVALID_INITIAL_TURN_GATE_VALUE,\n  E_INVALID_TURN_GATE_RESOLUTION,\n  E_TURN_GATE_TIMEOUT,\n  E_TURN_GATE_ABORTED,\n  E_NOT_A_SPOOL_READER,\n  E_INVALID_INITIAL_TOOL_CALL_VALUE,\n  E_INVALID_INITIAL_TOOL_VALUE,\n  E_INVALID_TOOL_ARGS,\n  E_TOOL_DOWNSTREAM_ERROR,\n  E_TOOL_ALREADY_REGISTERED,\n  E_INVALID_LLM_EXECUTION_CONTEXT,\n  E_LLM_EXECUTION_GATE_NOT_SUPPORTED,\n  E_LLM_EXECUTION_ALREADY_SIGNALLED,\n  E_INVALID_LLM_DISPATCH_INPUT,\n  E_DISPATCH_PIPELINE_ERROR,\n  E_LLM_EXECUTION_EXECUTOR_ERROR,\n} from './exceptions'\n\n// ── Types (re-exported via `export type *` form) ──────────────────────────────\n\nexport type {\n  BaseException,\n  TurnContext,\n  DispatchContext,\n  TurnGate,\n  RawIdentity,\n  RawMemory,\n  RawMessage,\n  MessageRole,\n  RawThought,\n  RawToolCall,\n  RawTool,\n  ToolHandler,\n  RawArtifactTool,\n  ArtifactToolHandler,\n  MergeOptions,\n  SpooledArtifactConstructor,\n  ToolMethodDescriptor,\n  RawTurnGate,\n  SpoolReader,\n  JsonArtifactFormat,\n  MarkdownHeadingEntry,\n  MarkdownCodeEntry,\n  MarkdownSection,\n  RawTurnContext,\n  ResolvedTurnContext,\n  MemoryRetrievalFn,\n  MessageRetrievalFn,\n  ThoughtRetrievalFn,\n  ToolCallRetrievalFn,\n  ToolsRetrievalFn,\n  RetrievableRetrievalFn,\n  StandingInstructionsRefreshFn,\n  StandingInstructionStoreFn,\n  StandingInstructionMutateFn,\n  StandingInstructionDeleteFn,\n  MemoryStoreFn,\n  MemoryMutateFn,\n  MemoryDeleteFn,\n  MessageStoreFn,\n  MessageMutateFn,\n  MessageDeleteFn,\n  ThoughtStoreFn,\n  ThoughtMutateFn,\n  ThoughtDeleteFn,\n  ToolCallStoreFn,\n  ToolCallMutateFn,\n  ToolCallDeleteFn,\n  RetrievableStoreFn,\n  RetrievableMutateFn,\n  RetrievableDeleteFn,\n  TurnRunnerConfig,\n  ResolvedTurnRunnerConfig,\n  TurnPipelineMiddlewareFn,\n  TurnStreamableContent,\n  TurnToolCallContent,\n  TurnStartEvent,\n  TurnEndEvent,\n  TurnGateClosedEvent,\n  ToolExecutionStartEvent,\n  ToolExecutionEndEvent,\n  EmitMessageFn,\n  EmitThoughtFn,\n  EmitToolCallFn,\n  EmitToolExecutionStartFn,\n  EmitToolExecutionEndFn,\n  OpenGateFn,\n  TurnEvents,\n  TurnEvent,\n  TurnEventListener,\n  TurnObservabilityEvents,\n  TurnObservabilityEvent,\n  TurnObservabilityEventListener,\n  RawDispatchContext,\n  DispatchMemoryRetrievalFn,\n  DispatchMessageRetrievalFn,\n  DispatchThoughtRetrievalFn,\n  DispatchToolCallRetrievalFn,\n  DispatchToolsRetrievalFn,\n  DispatchStandingInstructionsRefreshFn,\n  DispatchStandingInstructionStoreFn,\n  DispatchStandingInstructionMutateFn,\n  DispatchStandingInstructionDeleteFn,\n  DispatchMemoryStoreFn,\n  DispatchMemoryMutateFn,\n  DispatchMemoryDeleteFn,\n  DispatchMessageStoreFn,\n  DispatchMessageMutateFn,\n  DispatchMessageDeleteFn,\n  DispatchThoughtStoreFn,\n  DispatchThoughtMutateFn,\n  DispatchThoughtDeleteFn,\n  DispatchToolCallStoreFn,\n  DispatchToolCallMutateFn,\n  DispatchToolCallDeleteFn,\n  DispatchContextHooks,\n  DispatchContextHookRegistrations,\n  RawDispatchRunnerInput,\n  DispatchPipelineMiddlewareFn,\n  DispatchExecutorFn,\n  DispatchExecutorHelpers,\n  DispatchExecutorLogChannel,\n  DispatchExecutorLogEntry,\n  DispatchExecutorLogLevel,\n  LogEvent,\n  DispatchStartEvent,\n  DispatchEndEvent,\n  IterationStartEvent,\n  IterationEndEvent,\n  DispatchRunnerFunctionalHooks,\n  DispatchRunnerObservabilityHooks,\n  DispatchRunnerFunctionalHookRegistrations,\n  DispatchRunnerObservabilityHookRegistrations,\n} from './types'\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAWA,IAAa,UAAA"}

package/lib/classes/artifact_tool.d.ts

@@ -0,0 +1,129 @@
+import { Tool } from "./tool";
+import type { Registry } from "./registry";
+import type { Schema } from '@nhtio/validation';
+import type { Tokenizable } from "./tokenizable";
+import type { DispatchContext } from "../contracts/dispatch_context";
+/**
+ * The execution function for an {@link ArtifactTool}.
+ *
+ * @remarks
+ * Identical to the base tool handler except the return type is narrowed to
+ * `string | Tokenizable | Promise<string | Tokenizable>`. Forged artifact-query tools emit
+ * model-visible strings — the ADK wraps a bare-string return into a {@link @nhtio/adk!Tokenizable}
+ * at the result-wrapping site so downstream code can rely on
+ * `ToolCall.results instanceof Tokenizable` for every `ArtifactTool` invocation.
+ */
+export type ArtifactToolHandler = (args: unknown, ctx: DispatchContext, meta: Registry) => string | Tokenizable | Promise<string | Tokenizable>;
+/**
+ * Plain input object supplied to {@link ArtifactTool} at construction time.
+ *
+ * @remarks
+ * Mirrors the base `RawTool` except `artifactConstructor` is forbidden — an `ArtifactTool`
+ * emits a {@link @nhtio/adk!Tokenizable} directly into `ToolCall.results` and explicitly opts out of
+ * `SpooledArtifact` wrapping. The forbidden field is enforced by {@link ArtifactTool.schema}
+ * at construction time.
+ */
+export interface RawArtifactTool {
+    /** Unique identifier used in LLM tool definitions. Recommend lowercase snake_case. */
+    name: string;
+    /** Human-readable description passed to the model to explain what the tool does. */
+    description: string;
+    /** @nhtio/validation schema for the tool's input arguments. */
+    inputSchema: Schema;
+    /** Execution function. Returns a string or {@link @nhtio/adk!Tokenizable}; the ADK wraps a bare string into a `Tokenizable` at the result-wrapping site. */
+    handler: ArtifactToolHandler;
+    /** Optional arbitrary metadata for this tool. Defaults to `{}`. */
+    meta?: Record<string, unknown>;
+    /**
+     * When `true`, marks this tool as owned by a specific {@link @nhtio/adk!DispatchContext}.
+     *
+     * @remarks
+     * `ArtifactTool` instances produced by `SpooledArtifact.forgeTools(ctx)` set this to `true`
+     * so that `ToolRegistry.pruneEphemeral()` drops them at ctx-completion.
+     *
+     * @defaultValue `false`
+     */
+    ephemeral?: boolean;
+    /**
+     * When `true`, declares that this tool's output should be treated as **trusted developer/user
+     * intent** rather than as untrusted third-party text when surfaced to the model.
+     *
+     * @remarks
+     * Forged artifact-query tools default to `false` because their results are derived from
+     * spooled artifact bodies — which may themselves be untrusted upstream tool output. The
+     * trust signal does not promote handle-query results above the trust tier of the underlying
+     * artifact.
+     *
+     * @defaultValue `false`
+     */
+    trusted?: boolean;
+    /**
+     * Self-declared merge collision policy honoured by `ToolRegistry.merge`.
+     *
+     * @remarks
+     * Forged artifact-query tools set this to `'replace'` so that merging multiple
+     * `Subclass.forgeTools(ctx)` outputs (whose base-method tools overlap by name) resolves
+     * silently — the descriptors, snapshot, and handler behaviour are interchangeable across
+     * subclasses, so replacement is a behavioural no-op.
+     *
+     * @defaultValue `'throw'`
+     */
+    onCollision?: 'throw' | 'replace' | 'keep';
+}
+/**
+ * A {@link @nhtio/adk!Tool} subclass whose handler return value is wrapped directly in a
+ * {@link @nhtio/adk!Tokenizable} (not a {@link @nhtio/adk!SpooledArtifact}) when it
+ * lands on `ToolCall.results`.
+ *
+ * @remarks
+ * `ArtifactTool` is the canonical producer for **forged artifact-query tools** — the tools
+ * `SpooledArtifact.forgeTools(ctx)` emits so the model can `head`, `tail`, `grep`, `json_get`,
+ * `md_headings` (etc.) an artifact that is already in `ctx.turnToolCalls`.
+ *
+ * The difference from {@link @nhtio/adk!Tool} is structural, not stylistic:
+ *
+ * - A normal `Tool`'s handler returns bytes the ADK wraps in a fresh `SpooledArtifact`.
+ *   The artifact lands in `ToolCall.results`, joins `ctx.turnToolCalls`, and is itself a
+ *   first-class queryable artifact in the turn.
+ * - An `ArtifactTool`'s handler returns a string that is **already the model-visible answer**
+ *   to a query against an existing artifact. The ADK wraps it in a `Tokenizable` rather
+ *   than a `SpooledArtifact`; nothing new is queryable on its own. Subsequent
+ *   `forgeTools(ctx)` calls exclude `ToolCall`s produced by an `ArtifactTool` from the
+ *   `callId` enum (via the `ToolCall.fromArtifactTool` marker) — this is the structural fix
+ *   that breaks the otherwise-recursive grep-on-the-grep-result loop.
+ *
+ * Consumers who want to build their own artifact-query tools (e.g. for a domain-specific
+ * spooled subclass not shipped by the ADK) should extend or instantiate this class.
+ */
+export declare class ArtifactTool extends Tool {
+    /**
+     * Validator schema that accepts a {@link RawArtifactTool} object.
+     *
+     * @remarks
+     * Differs from {@link @nhtio/adk!Tool.schema} by forbidding `artifactConstructor` — wrapping is
+     * exactly the thing this class opts out of. Typed identically to {@link @nhtio/adk!Tool.schema} so the
+     * subclass relationship `class ArtifactTool extends Tool` remains structurally sound; the
+     * runtime validation rules still differ as declared by `rawArtifactToolSchema`.
+     */
+    static schema: typeof Tool.schema;
+    /**
+     * Returns `true` if `value` is an {@link ArtifactTool} instance.
+     *
+     * @remarks
+     * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety — `instanceof` would fail for instances
+     * created in a different module copy or VM context.
+     *
+     * @param value - The value to test.
+     * @returns `true` when `value` is an {@link ArtifactTool} instance.
+     */
+    static isArtifactTool(value: unknown): value is ArtifactTool;
+    /**
+     * @param raw - Raw tool input validated against {@link ArtifactTool.schema}.
+     *
+     * @throws {@link @nhtio/adk!E_INVALID_INITIAL_TOOL_VALUE} when `raw` does not satisfy
+     *   {@link ArtifactTool.schema} (most commonly, when `artifactConstructor` is supplied — it is
+     *   explicitly forbidden on this class) or when the base {@link @nhtio/adk!Tool} constructor rejects the
+     *   input for any reason.
+     */
+    constructor(raw: RawArtifactTool);
+}

package/lib/classes/base_exception.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Base class for all structured exceptions in the ADK.
+ *
+ * @remarks
+ * Subclasses should declare static `code`, `status`, `fatal`, and optionally `help` to avoid
+ * repeating those values on every instance. Instance-level options always take precedence over
+ * static defaults, so a single exception class can still be thrown with per-site overrides when
+ * needed.
+ *
+ * The runtime cross-realm guard is inlined here rather than imported from `../utils/guards`
+ * to break a circular-import chain: `guards` depends on `validation`, which extends
+ * `BaseException`. Importing the shared `isInstanceOf` helper into this file would create a
+ * load-order cycle that leaves `BaseException` undefined when `ValidationException extends
+ * BaseException` evaluates.
+ */
+export declare class BaseException extends Error {
+    /**
+     * Returns `true` if `value` is a {@link BaseException} instance.
+     *
+     * @remarks
+     * Performs cross-realm-safe detection: tries `instanceof`, then `Symbol.hasInstance`, then
+     * constructor-name comparison. The ADK does not export the `BaseException` class itself
+     * as a constructable value — use this guard plus the {@link BaseException} type for runtime
+     * detection and TypeScript narrowing.
+     *
+     * @param value - The value to test.
+     * @returns `true` when `value` is a {@link BaseException} instance.
+     */
+    static isBaseException(value: unknown): value is BaseException;
+    /**
+     * Default help text inherited by all instances unless overridden at the throw site.
+     */
+    static help?: string;
+    /**
+     * Default machine-readable error code inherited by all instances.
+     */
+    static code?: string;
+    /**
+     * Default HTTP status code inherited by all instances.
+     */
+    static status?: number;
+    /**
+     * Whether exceptions of this class are fatal by default.
+     */
+    static fatal?: boolean;
+    /**
+     * Default message used when no message is supplied to the constructor.
+     */
+    static message?: string;
+    /**
+     * Name of the class that raised the exception.
+     */
+    name: string;
+    /**
+     * Human-readable guidance for resolving or reporting this error.
+     */
+    help?: string;
+    /**
+     * Machine-readable error code for narrowing exception-handling logic.
+     */
+    code?: string;
+    /**
+     * HTTP status code associated with this error.
+     */
+    status?: number;
+    /**
+     * When `true`, the ADK treats this error as unrecoverable and should halt the agent loop.
+     */
+    fatal?: boolean;
+    /**
+     * @param message - Human-readable error message. Falls back to the static `message` on the
+     *   subclass if omitted.
+     * @param options - Standard `ErrorOptions` extended with `code`, `status`, and `fatal`
+     *   overrides. Static defaults on the subclass are used when these are absent.
+     */
+    constructor(message?: string, options?: ErrorOptions & {
+        code?: string;
+        status?: number;
+        fatal?: boolean;
+    });
+    get [Symbol.toStringTag](): string;
+    toString(): string;
+}

package/lib/classes/identity.d.ts

@@ -0,0 +1,71 @@
+import { Tokenizable } from "./tokenizable";
+/**
+ * Plain input object supplied to {@link Identity} at construction time.
+ *
+ * @remarks
+ * Validated against `rawIdentitySchema` before the `Identity` instance is created.
+ */
+export interface RawIdentity {
+    /**
+     * The system-facing identifier for this participant.
+     *
+     * @remarks
+     * Used internally to correlate messages to a specific participant — e.g. a database ID or
+     * a username. Never sent to the model directly; use `representation` for that.
+     */
+    identifier: string | number;
+    /**
+     * How this participant should be presented to the model.
+     *
+     * @remarks
+     * Accepts a plain string or an existing {@link @nhtio/adk!Tokenizable} instance. This is what the model
+     * sees when it needs to distinguish between participants of the same role.
+     */
+    representation: string | Tokenizable;
+}
+/**
+ * An immutable, validated participant identity attached to a {@link @nhtio/adk!Message}.
+ *
+ * @remarks
+ * Carries two distinct representations of the same participant: `identifier` is the
+ * system-facing key (e.g. a database ID) used to correlate messages programmatically;
+ * `representation` is what the model sees when it needs to distinguish between participants
+ * sharing the same role. The `representation` is always a {@link @nhtio/adk!Tokenizable} so token cost
+ * can be estimated inline.
+ */
+export declare class Identity {
+    #private;
+    /**
+     * Validator schema that accepts a {@link RawIdentity} object.
+     *
+     * @remarks
+     * Reusable fragment for any schema that needs to validate or nest an identity — for example,
+     * as a required field inside a message schema.
+     */
+    static schema: import("@nhtio/validation").ObjectSchema<RawIdentity>;
+    /**
+     * Returns `true` if `value` is an {@link Identity} instance.
+     *
+     * @remarks
+     * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety — `instanceof` would fail for instances
+     * created in a different module copy or VM context.
+     *
+     * @param value - The value to test.
+     * @returns `true` when `value` is an {@link Identity} instance.
+     */
+    static isIdentity(value: unknown): value is Identity;
+    /**
+     * The system-facing identifier for this participant — never sent to the model directly.
+     */
+    readonly identifier: string | number;
+    /**
+     * How this participant is presented to the model, as a {@link @nhtio/adk!Tokenizable} for inline
+     * token estimation.
+     */
+    readonly representation: Tokenizable;
+    /**
+     * @param raw - The raw identity input validated against `rawIdentitySchema`.
+     * @throws {@link @nhtio/adk!E_INVALID_INITIAL_IDENTITY_VALUE} when `raw` does not satisfy the schema.
+     */
+    constructor(raw: RawIdentity);
+}

package/lib/classes/media.d.ts

@@ -0,0 +1,326 @@
+import { Registry } from "./registry";
+import type { MediaReader } from "../contracts/media_reader";
+/**
+ * The set of supported media kinds.
+ *
+ * @remarks
+ * Modality coverage is asymmetric across providers. The framework defines no
+ * `supportedModalities` field — how a battery handles a modality it cannot natively render is
+ * the battery author's call (see `unsupportedMediaPolicy` on the OpenAI Chat Completions
+ * battery).
+ */
+export declare const MediaKind: readonly [
+    "image",
+    "audio",
+    "video",
+    "document"
+];
+/**
+ * Union of all recognised media kind identifier strings.
+ */
+export type MediaKind = (typeof MediaKind)[number];
+/**
+ * Provenance axis. *Who is the framework willing to vouch for as the source of these bytes?*
+ *
+ * @remarks
+ * Mirrors `RetrievableTrustTier` deliberately — same vocabulary, same question:
+ * *did this content come from a place the agent should treat as authoritative?*
+ *
+ * - `'first-party'` — deployer-vetted bytes (tool output the operator authored, signed
+ *   internal assets).
+ * - `'third-party-public'` — open-web fetches, public APIs, public corpora.
+ * - `'third-party-private'` — user uploads, partner APIs, private corpora.
+ */
+export declare const MediaTrustTier: readonly [
+    "first-party",
+    "third-party-public",
+    "third-party-private"
+];
+export type MediaTrustTier = (typeof MediaTrustTier)[number];
+/**
+ * Modality-hazard axis. *How dangerous is it to let the model decode these bytes?*
+ *
+ * @remarks
+ * Orthogonal to provenance — a first-party trusted PDF can still carry hidden text layers; a
+ * third-party-public raw image can still be encoded as opaque pixels with adversarial
+ * perturbations.
+ *
+ * - `'inert'` — bytes the model never decodes as instructions (e.g. a handle that is never
+ *   inlined into the prompt).
+ * - `'extractable-instructions'` — text-bearing media: PDFs, screenshots with UI text, documents.
+ *   Hazard is OCR / embedded-text-layer reads.
+ * - `'opaque-perceptual'` — raw vision/audio/video the model encodes directly. Hazard is
+ *   steganographic LSB prompts, adversarial perturbations, ultrasonic audio — invisible to any
+ *   pre-screen.
+ *
+ * See `/the-loop/trust-tiers/media` and its research sub-page `/the-loop/trust-tiers/media/research`.
+ */
+export declare const MediaModalityHazard: readonly [
+    "inert",
+    "extractable-instructions",
+    "opaque-perceptual"
+];
+export type MediaModalityHazard = (typeof MediaModalityHazard)[number];
+/**
+ * Per-entry shape stored in a {@link Media}'s `stash` register.
+ *
+ * @remarks
+ * Each entry carries its own trust tier so render code can route derived text (OCR, captions,
+ * transcripts) through its own envelope independent of the parent media. How a battery or
+ * middleware assigns those entry-level tiers is the implementor's call — the primitive contract
+ * does not enforce a "downgrade derived interpretation from possibly-adversarial bytes" policy.
+ */
+export interface MediaStashEntry {
+    /** The value of the entry — any serialisable shape the consumer wants to store. */
+    value: unknown;
+    /** Trust tier for this specific entry; routed independently of the parent media. */
+    trustTier: MediaTrustTier;
+    /** Optional pointer to the parent Media id this entry was derived from. */
+    derivedFromMedia?: string;
+}
+/**
+ * Plain input object supplied to {@link Media} at construction time.
+ *
+ * @remarks
+ * Validated against `rawMediaSchema` before the `Media` instance is created.
+ */
+export interface RawMedia {
+    /**
+     * Stable unique identifier for this media instance. Required for strict symmetry with
+     * `Message.id` and `ToolCall.id`. When omitted, a fresh UUIDv6 is assigned at construction
+     * time.
+     */
+    id?: string;
+    /** The media kind. See {@link MediaKind}. */
+    kind: MediaKind;
+    /** The MIME type of the underlying bytes. */
+    mimeType: string;
+    /** Filename used by providers that key on it (e.g. OpenAI `file.filename`). */
+    filename: string;
+    /** Re-openable byte source. See {@link @nhtio/adk!MediaReader}. */
+    reader: MediaReader;
+    /**
+     * Trust tier declared at construction time. Required — there is NO default.
+     * See {@link MediaTrustTier}.
+     */
+    trustTier: MediaTrustTier;
+    /**
+     * Modality hazard declared at construction time. Required — there is NO default.
+     * See {@link MediaModalityHazard}.
+     */
+    modalityHazard: MediaModalityHazard;
+    /** Optional provenance pointer (URL, tool name, etc.) for audit / events. */
+    source?: string;
+    /**
+     * Free-form per-instance metadata register. Middleware pipelines append to this — typically
+     * with a text description, transcript, caption, or alt-text — so downstream code that cannot
+     * consume the media natively has a model-readable fallback. No keys are reserved by the
+     * framework. Defaults to `{}`.
+     */
+    stash?: Record<string, MediaStashEntry>;
+}
+/**
+ * Shape returned by {@link Media.toJSON}. Metadata-only — bytes and the reader are stripped so
+ * naive event/log serialisation never materialises bytes.
+ */
+export interface SerializedMedia {
+    id: string;
+    kind: MediaKind;
+    mimeType: string;
+    filename: string;
+    source?: string;
+    trustTier: MediaTrustTier;
+    modalityHazard: MediaModalityHazard;
+    stash: Record<string, MediaStashEntry>;
+    byteLength?: number;
+}
+/**
+ * Lazy, re-openable view over a binary asset (image, audio, video, document).
+ *
+ * @remarks
+ * Dual-peer to {@link @nhtio/adk!Tokenizable} (silo) and {@link @nhtio/adk!SpooledArtifact}
+ * (handle). Wraps a {@link @nhtio/adk!MediaReader} contract — the framework owns the contract, the
+ * implementor owns the storage backend. Bytes are reached only through the reader; the primitive
+ * itself never inlines bytes.
+ *
+ * Construction requires `trustTier` and `modalityHazard` — the framework refuses to guess
+ * provenance or decoding hazard. Ergonomic factories ({@link Media.userAttachment},
+ * {@link Media.toolGenerated}, {@link Media.retrievedPublic}, {@link Media.retrievedPrivate})
+ * force the labelling decision at the call site without becoming defaults on the bare
+ * constructor.
+ */
+export declare class Media {
+    #private;
+    /**
+     * Validator schema that accepts a {@link RawMedia} object.
+     */
+    static schema: import("@nhtio/validation").ObjectSchema<RawMedia>;
+    /**
+     * The set of recognised media kinds. Exposed for downstream schemas that need to discriminate
+     * on `kind`.
+     */
+    static MediaKind: readonly [
+        "image",
+        "audio",
+        "video",
+        "document"
+    ];
+    /**
+     * The set of recognised trust tiers.
+     */
+    static MediaTrustTier: readonly [
+        "first-party",
+        "third-party-public",
+        "third-party-private"
+    ];
+    /**
+     * The set of recognised modality hazards.
+     */
+    static MediaModalityHazard: readonly [
+        "inert",
+        "extractable-instructions",
+        "opaque-perceptual"
+    ];
+    /**
+     * Returns `true` if `value` is a {@link Media} instance.
+     *
+     * @remarks
+     * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety.
+     *
+     * @param value - The value to test.
+     * @returns `true` when `value` is a {@link Media} instance.
+     */
+    static isMedia(value: unknown): value is Media;
+    /** Stable unique identifier. */
+    readonly id: string;
+    /** Media kind. */
+    readonly kind: MediaKind;
+    /** MIME type of the underlying bytes. */
+    readonly mimeType: string;
+    /** Filename surfaced to providers that key on it. */
+    readonly filename: string;
+    /** Optional provenance pointer. */
+    readonly source: string | undefined;
+    /** Trust tier declared at construction time. */
+    readonly trustTier: MediaTrustTier;
+    /** Modality hazard declared at construction time. */
+    readonly modalityHazard: MediaModalityHazard;
+    /** Mutable per-instance metadata register; middleware pipelines append to this. */
+    readonly stash: Registry;
+    /**
+     * @param raw - The raw media input validated against `rawMediaSchema`.
+     * @throws {@link @nhtio/adk/exceptions!E_INVALID_INITIAL_MEDIA_VALUE} when `raw` does not satisfy the schema.
+     * @throws {@link @nhtio/adk/exceptions!E_NOT_A_MEDIA_READER} when `raw.reader` does not implement {@link @nhtio/adk!MediaReader}.
+     */
+    constructor(raw: RawMedia);
+    /**
+     * Re-opens the underlying byte source and returns a fresh ReadableStream.
+     *
+     * @returns A drainable `ReadableStream` over the underlying bytes.
+     */
+    stream(): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * Returns the total number of bytes in the underlying data, or `undefined` if unknown.
+     *
+     * @returns The byte length, or `undefined` when the underlying source cannot report it.
+     */
+    byteLength(): Promise<number | undefined>;
+    /**
+     * Drains the reader's stream and returns the underlying bytes as a single `Uint8Array`.
+     *
+     * @remarks
+     * Convenience for callers that need the full buffer (e.g. inline base64 encoding). Forces
+     * full materialisation — large assets should be piped through {@link Media.stream} instead.
+     */
+    asBytes(): Promise<Uint8Array>;
+    /**
+     * Drains the reader's stream and returns the underlying bytes as a base64 string.
+     *
+     * @remarks
+     * Cross-environment: prefers Node's `Buffer.from(buf).toString('base64')` when available;
+     * otherwise chunk-encodes through `btoa` with a 0x8000-byte window to avoid stack overflow
+     * on large buffers.
+     */
+    asBase64(): Promise<string>;
+    /**
+     * Returns the metadata-only serialisation of this Media. Bytes and the reader are stripped
+     * so naive event/log serialisation never materialises bytes.
+     *
+     * @remarks
+     * Implementations that have cheap, already-cached `byteLength` may opt to include it; this
+     * default implementation omits it to preserve the "lazy by default" invariant. Consumers that
+     * need byteLength on the serialised payload should call `await media.byteLength()` and merge
+     * the result.
+     */
+    toJSON(): SerializedMedia;
+    /**
+     * Factory: constructs a {@link Media} representing a user-supplied attachment.
+     *
+     * @remarks
+     * Pre-fills `trustTier: 'third-party-private'` and derives `modalityHazard` from `kind`
+     * (`document` → `'extractable-instructions'`; everything else → `'opaque-perceptual'`).
+     * Use the bare constructor when the conservative kind→hazard mapping is wrong for your case.
+     */
+    static userAttachment(args: {
+        id?: string;
+        kind: MediaKind;
+        mimeType: string;
+        filename: string;
+        reader: MediaReader;
+        source?: string;
+        stash?: Record<string, MediaStashEntry>;
+    }): Media;
+    /**
+     * Factory: constructs a {@link Media} produced by a first-party tool.
+     *
+     * @remarks
+     * Pre-fills `trustTier: 'first-party'` and derives `modalityHazard` from `kind`.
+     */
+    static toolGenerated(args: {
+        id?: string;
+        kind: MediaKind;
+        mimeType: string;
+        filename: string;
+        reader: MediaReader;
+        source?: string;
+        stash?: Record<string, MediaStashEntry>;
+    }): Media;
+    /**
+     * Factory: constructs a {@link Media} retrieved from a public third-party source.
+     *
+     * @remarks
+     * Pre-fills `trustTier: 'third-party-public'` and derives `modalityHazard` from `kind`.
+     */
+    static retrievedPublic(args: {
+        id?: string;
+        kind: MediaKind;
+        mimeType: string;
+        filename: string;
+        reader: MediaReader;
+        source?: string;
+        stash?: Record<string, MediaStashEntry>;
+    }): Media;
+    /**
+     * Factory: constructs a {@link Media} retrieved from a private third-party source.
+     *
+     * @remarks
+     * Pre-fills `trustTier: 'third-party-private'` and derives `modalityHazard` from `kind`.
+     */
+    static retrievedPrivate(args: {
+        id?: string;
+        kind: MediaKind;
+        mimeType: string;
+        filename: string;
+        reader: MediaReader;
+        source?: string;
+        stash?: Record<string, MediaStashEntry>;
+    }): Media;
+}
+/**
+ * Returns `true` if `value` is a {@link Media} instance.
+ *
+ * @remarks
+ * Module-level convenience alias for {@link Media.isMedia}. Uses {@link @nhtio/adk!isInstanceOf} for
+ * cross-realm safety.
+ */
+export declare const isMedia: (value: unknown) => value is Media;