@nhtio/adk 0.1.0-master-d3feb810 → 0.1.0-master-445a9ed0

package/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","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"}
+{"version":3,"file":"index.cjs","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  MediaBytesStoreFn,\n  RetrievableBytesStoreFn,\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  DispatchMediaBytesStoreFn,\n  DispatchRetrievableBytesStoreFn,\n  ConduitBytes,\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/index.d.ts

@@ -15,4 +15,4 @@ export { TurnRunner } from "./turn_runner";
 export { DispatchRunner } from "./dispatch_runner";
 export { isInstanceOf, isError, isObject, isBaseException, isIdentity, isMemory, isMessage, isRegistry, isThought, isTokenizable, isTool, isArtifactTool, isToolCall, isToolRegistry, isTurnGate, isSpooledArtifact, isSpooledArtifactConstructor, isSpooledJsonArtifact, isSpooledMarkdownArtifact, isTurnContext, isTurnRunner, isDispatchContext, isDispatchRunner, } from "./guards";
 export { ValidationException, E_INVALID_TURN_RUNNER_CONFIG, E_INVALID_TURN_CONTEXT, E_INPUT_PIPELINE_ERROR, E_OUTPUT_PIPELINE_ERROR, E_PIPELINE_SHORT_CIRCUITED, E_INVALID_INITIAL_REGISTRY_VALUE, E_INVALID_INITIAL_MEMORY_VALUE, E_INVALID_INITIAL_MESSAGE_VALUE, E_INVALID_INITIAL_IDENTITY_VALUE, E_INVALID_INITIAL_THOUGHT_VALUE, E_INVALID_INITIAL_TURN_GATE_VALUE, E_INVALID_TURN_GATE_RESOLUTION, E_TURN_GATE_TIMEOUT, E_TURN_GATE_ABORTED, E_NOT_A_SPOOL_READER, E_INVALID_INITIAL_TOOL_CALL_VALUE, E_INVALID_INITIAL_TOOL_VALUE, E_INVALID_TOOL_ARGS, E_TOOL_DOWNSTREAM_ERROR, E_TOOL_ALREADY_REGISTERED, E_INVALID_LLM_EXECUTION_CONTEXT, E_LLM_EXECUTION_GATE_NOT_SUPPORTED, E_LLM_EXECUTION_ALREADY_SIGNALLED, E_INVALID_LLM_DISPATCH_INPUT, E_DISPATCH_PIPELINE_ERROR, E_LLM_EXECUTION_EXECUTOR_ERROR, } from "./exceptions";
-export type { BaseException, TurnContext, DispatchContext, TurnGate, RawIdentity, RawMemory, RawMessage, MessageRole, RawThought, RawToolCall, RawTool, ToolHandler, RawArtifactTool, ArtifactToolHandler, MergeOptions, SpooledArtifactConstructor, ToolMethodDescriptor, RawTurnGate, SpoolReader, JsonArtifactFormat, MarkdownHeadingEntry, MarkdownCodeEntry, MarkdownSection, RawTurnContext, ResolvedTurnContext, MemoryRetrievalFn, MessageRetrievalFn, ThoughtRetrievalFn, ToolCallRetrievalFn, ToolsRetrievalFn, RetrievableRetrievalFn, StandingInstructionsRefreshFn, StandingInstructionStoreFn, StandingInstructionMutateFn, StandingInstructionDeleteFn, MemoryStoreFn, MemoryMutateFn, MemoryDeleteFn, MessageStoreFn, MessageMutateFn, MessageDeleteFn, ThoughtStoreFn, ThoughtMutateFn, ThoughtDeleteFn, ToolCallStoreFn, ToolCallMutateFn, ToolCallDeleteFn, RetrievableStoreFn, RetrievableMutateFn, RetrievableDeleteFn, TurnRunnerConfig, ResolvedTurnRunnerConfig, TurnPipelineMiddlewareFn, TurnStreamableContent, TurnToolCallContent, TurnStartEvent, TurnEndEvent, TurnGateClosedEvent, ToolExecutionStartEvent, ToolExecutionEndEvent, EmitMessageFn, EmitThoughtFn, EmitToolCallFn, EmitToolExecutionStartFn, EmitToolExecutionEndFn, OpenGateFn, TurnEvents, TurnEvent, TurnEventListener, TurnObservabilityEvents, TurnObservabilityEvent, TurnObservabilityEventListener, RawDispatchContext, DispatchMemoryRetrievalFn, DispatchMessageRetrievalFn, DispatchThoughtRetrievalFn, DispatchToolCallRetrievalFn, DispatchToolsRetrievalFn, DispatchStandingInstructionsRefreshFn, DispatchStandingInstructionStoreFn, DispatchStandingInstructionMutateFn, DispatchStandingInstructionDeleteFn, DispatchMemoryStoreFn, DispatchMemoryMutateFn, DispatchMemoryDeleteFn, DispatchMessageStoreFn, DispatchMessageMutateFn, DispatchMessageDeleteFn, DispatchThoughtStoreFn, DispatchThoughtMutateFn, DispatchThoughtDeleteFn, DispatchToolCallStoreFn, DispatchToolCallMutateFn, DispatchToolCallDeleteFn, DispatchContextHooks, DispatchContextHookRegistrations, RawDispatchRunnerInput, DispatchPipelineMiddlewareFn, DispatchExecutorFn, DispatchExecutorHelpers, DispatchExecutorLogChannel, DispatchExecutorLogEntry, DispatchExecutorLogLevel, LogEvent, DispatchStartEvent, DispatchEndEvent, IterationStartEvent, IterationEndEvent, DispatchRunnerFunctionalHooks, DispatchRunnerObservabilityHooks, DispatchRunnerFunctionalHookRegistrations, DispatchRunnerObservabilityHookRegistrations, } from "./types";
+export type { BaseException, TurnContext, DispatchContext, TurnGate, RawIdentity, RawMemory, RawMessage, MessageRole, RawThought, RawToolCall, RawTool, ToolHandler, RawArtifactTool, ArtifactToolHandler, MergeOptions, SpooledArtifactConstructor, ToolMethodDescriptor, RawTurnGate, SpoolReader, JsonArtifactFormat, MarkdownHeadingEntry, MarkdownCodeEntry, MarkdownSection, RawTurnContext, ResolvedTurnContext, MemoryRetrievalFn, MessageRetrievalFn, ThoughtRetrievalFn, ToolCallRetrievalFn, ToolsRetrievalFn, RetrievableRetrievalFn, StandingInstructionsRefreshFn, StandingInstructionStoreFn, StandingInstructionMutateFn, StandingInstructionDeleteFn, MemoryStoreFn, MemoryMutateFn, MemoryDeleteFn, MessageStoreFn, MessageMutateFn, MessageDeleteFn, ThoughtStoreFn, ThoughtMutateFn, ThoughtDeleteFn, ToolCallStoreFn, ToolCallMutateFn, ToolCallDeleteFn, RetrievableStoreFn, RetrievableMutateFn, RetrievableDeleteFn, MediaBytesStoreFn, RetrievableBytesStoreFn, TurnRunnerConfig, ResolvedTurnRunnerConfig, TurnPipelineMiddlewareFn, TurnStreamableContent, TurnToolCallContent, TurnStartEvent, TurnEndEvent, TurnGateClosedEvent, ToolExecutionStartEvent, ToolExecutionEndEvent, EmitMessageFn, EmitThoughtFn, EmitToolCallFn, EmitToolExecutionStartFn, EmitToolExecutionEndFn, OpenGateFn, TurnEvents, TurnEvent, TurnEventListener, TurnObservabilityEvents, TurnObservabilityEvent, TurnObservabilityEventListener, RawDispatchContext, DispatchMemoryRetrievalFn, DispatchMessageRetrievalFn, DispatchThoughtRetrievalFn, DispatchToolCallRetrievalFn, DispatchToolsRetrievalFn, DispatchStandingInstructionsRefreshFn, DispatchStandingInstructionStoreFn, DispatchStandingInstructionMutateFn, DispatchStandingInstructionDeleteFn, DispatchMemoryStoreFn, DispatchMemoryMutateFn, DispatchMemoryDeleteFn, DispatchMessageStoreFn, DispatchMessageMutateFn, DispatchMessageDeleteFn, DispatchThoughtStoreFn, DispatchThoughtMutateFn, DispatchThoughtDeleteFn, DispatchToolCallStoreFn, DispatchToolCallMutateFn, DispatchToolCallDeleteFn, DispatchMediaBytesStoreFn, DispatchRetrievableBytesStoreFn, ConduitBytes, DispatchContextHooks, DispatchContextHookRegistrations, RawDispatchRunnerInput, DispatchPipelineMiddlewareFn, DispatchExecutorFn, DispatchExecutorHelpers, DispatchExecutorLogChannel, DispatchExecutorLogEntry, DispatchExecutorLogLevel, LogEvent, DispatchStartEvent, DispatchEndEvent, IterationStartEvent, IterationEndEvent, DispatchRunnerFunctionalHooks, DispatchRunnerObservabilityHooks, DispatchRunnerFunctionalHookRegistrations, DispatchRunnerObservabilityHookRegistrations, } from "./types";

package/index.mjs

@@ -1,16 +1,16 @@
 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 { i as Identity, n as Message, r as Memory, t as Thought } from "./thought-DDqjQu3m.mjs";
+import { t as Tool } from "./tool-q4LskG7K.mjs";
+import { i as ArtifactTool, r as implementsSpoolReader, t as SpooledArtifact } from "./spooled_artifact-B_tVDDdB.mjs";
+import { n as fromWebFile, o as Retrievable, r as inMemoryMediaReader, t as fromFetch } from "./common-aFmr9Oqs.mjs";
+import { a as mediaReaderSchema, i as implementsMediaReader, n as Media, r as isMedia, t as ToolCall } from "./tool_call-BKIdAAoY.mjs";
+import { n as SpooledJsonArtifact, t as SpooledMarkdownArtifact } from "./spooled_markdown_artifact-DWWak35I.mjs";
 import "./exceptions.mjs";
-import { t as DispatchRunner } from "./dispatch_runner-9j6bXHL3.mjs";
+import { t as DispatchRunner } from "./dispatch_runner-OimGCkk7.mjs";
 import "./dispatch_runner.mjs";
-import { t as TurnRunner } from "./turn_runner-y7eyEcJH.mjs";
+import { t as TurnRunner } from "./turn_runner-DRBLN2Y_.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
@@ -24,7 +24,7 @@ import "./turn_runner.mjs";
 *
 * @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-d3feb810";
+var version = "0.1.0-master-445a9ed0";
 //#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 };
 

package/index.mjs.map

@@ -1 +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"}
+{"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  MediaBytesStoreFn,\n  RetrievableBytesStoreFn,\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  DispatchMediaBytesStoreFn,\n  DispatchRetrievableBytesStoreFn,\n  ConduitBytes,\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/retrievable.d.ts

@@ -1,5 +1,7 @@
 import { Tokenizable } from "./tokenizable";
+import { SpooledArtifact } from "./spooled_artifact";
 import type { DateTime } from 'luxon';
+import type { TokenEncoding } from "./tokenizable";
 /**
  * Trust-tier discriminator declared by the retrieval middleware at construction time. Drives
  * which envelope the LLM battery wraps the record in.
@@ -33,8 +35,15 @@ export interface RawRetrievable {
      * rendered envelope, so it must be unguessable from the payload.
      */
     id: string;
-    /** The retrieved content as a plain string or an existing {@link @nhtio/adk!Tokenizable} instance. */
-    content: string | Tokenizable;
+    /**
+     * The retrieved content. A plain `string` or {@link @nhtio/adk!Tokenizable} for small inline text, or a
+     * {@link @nhtio/adk!SpooledArtifact} when the extracted text is large and lives in a consumer
+     * {@link @nhtio/adk!ByteStore} (persist it via {@link @nhtio/adk!DispatchContext.storeRetrievableBytes}, wrap
+     * the returned reader in a `SpooledArtifact`, and pass it here). Reader-backed content keeps the
+     * body out of the permanent heap, but token estimation and render still materialise it
+     * transiently (see {@link Retrievable.estimateTokens}).
+     */
+    content: string | Tokenizable | SpooledArtifact;
     /**
      * Trust tier declared by the retrieval middleware at construction time. Required — there is
      * NO default. The decision must be conscious. See {@link RetrievableTrustTier}.
@@ -78,8 +87,13 @@ export declare class Retrievable {
     static isRetrievable(value: unknown): value is Retrievable;
     /** Stable unique identifier for this retrieved record. */
     readonly id: string;
-    /** The retrieved content as a {@link @nhtio/adk!Tokenizable} for inline token estimation. */
-    readonly content: Tokenizable;
+    /**
+     * The retrieved content: a {@link @nhtio/adk!Tokenizable} (inline text) or a
+     * {@link @nhtio/adk!SpooledArtifact} (reader-backed, large text living in a consumer store). Use
+     * {@link Retrievable.estimateTokens} for budgeting and {@link Retrievable.contentString} to
+     * materialise the body at render time.
+     */
+    readonly content: Tokenizable | SpooledArtifact;
     /** Trust tier declared by the retrieval middleware. */
     readonly trustTier: RetrievableTrustTier;
     /** Optional provenance string. */
@@ -97,4 +111,33 @@ export declare class Retrievable {
      * @throws {@link @nhtio/adk/exceptions!E_INVALID_INITIAL_RETRIEVABLE_VALUE} when `raw` does not satisfy the schema.
      */
     constructor(raw: RawRetrievable);
+    /**
+     * Estimates the token count of the content under `encoding`.
+     *
+     * @remarks
+     * Delegates to the content's own `estimateTokens`: synchronous for a {@link @nhtio/adk!Tokenizable}
+     * (returns `number`), asynchronous for a {@link @nhtio/adk!SpooledArtifact} (returns
+     * `Promise<number>`, reading the bytes from the backing store on demand). Both shapes satisfy the
+     * adapter's token-budget path, which already awaits estimates.
+     *
+     * Note: the `SpooledArtifact` branch materialises the full decoded string transiently to count
+     * tokens — reader-backing keeps the body off the *permanent* heap, but does not eliminate the
+     * transient allocation at budgeting time.
+     *
+     * @param encoding - The encoding identifier to use for counting.
+     * @returns The estimated token count.
+     */
+    estimateTokens(encoding: TokenEncoding): number | Promise<number>;
+    /**
+     * Returns the content body as a single string.
+     *
+     * @remarks
+     * For a {@link @nhtio/adk!Tokenizable} this is synchronous in effect (resolved immediately); for a
+     * {@link @nhtio/adk!SpooledArtifact} it reads the full body from the backing store via
+     * {@link @nhtio/adk!SpooledArtifact.asString}. Always returns a `Promise` so callers have one
+     * code path; render helpers `await` it at the point the trust-tier envelope is built.
+     *
+     * @returns The full content body as a string.
+     */
+    contentString(): Promise<string>;
 }

package/lib/contracts/byte_store.d.ts

@@ -0,0 +1,93 @@
+import type { SpoolReader } from "./spool_reader";
+import type { MediaReader } from "./media_reader";
+/**
+ * Unified "give bytes, get a reader" persistence contract.
+ *
+ * @remarks
+ * For the purposes of storage there is no meaningful distinction between text and binary — bytes
+ * are bytes. `ByteStore` is the single low-level shape every ADK storage layer implements: hand it
+ * bytes under an `id`, get back a replayable reader `R`; read or delete by the same `id` later. The
+ * generic `R` is the reader the store hands out — different reader contracts (line-indexed
+ * {@link @nhtio/adk!SpoolReader} vs binary-streamed {@link @nhtio/adk!MediaReader}) are
+ * distinguished by the `R` instantiation, not by separate store interfaces. See the {@link SpoolStore}
+ * and {@link MediaStore} aliases for the two concrete semantics.
+ *
+ * `write` accepts a `string`, a `Uint8Array`, or a `ReadableStream<Uint8Array>`. The stream form is
+ * the point of the contract: a durable store can persist an arbitrarily large payload straight to
+ * disk/object storage without first materializing it in memory. **String input is encoded as
+ * UTF-8.** The returned reader is only guaranteed readable once the `write` result has resolved.
+ *
+ * All three methods may be synchronous or asynchronous so that in-memory implementations are not
+ * forced to pay promise overhead while I/O-backed implementations stay async. Note that any
+ * implementation accepting a `ReadableStream` must return a `Promise` for that input — draining a
+ * stream cannot be synchronous.
+ */
+export interface ByteStore<R> {
+    /**
+     * Persists `bytes` under `id` and returns a reader over them.
+     *
+     * @remarks
+     * Re-writing the same `id` replaces the prior entry. `string` input is encoded as UTF-8;
+     * `Uint8Array` and `ReadableStream<Uint8Array>` are stored byte-faithfully. Stream input
+     * necessarily resolves asynchronously.
+     *
+     * @param id - Identifier used to retrieve or delete the bytes later.
+     * @param bytes - The payload, as a `string`, `Uint8Array`, or `ReadableStream<Uint8Array>`.
+     * @returns A reader over the stored bytes (or a `Promise` of one).
+     */
+    write(id: string, bytes: string | Uint8Array | ReadableStream<Uint8Array>): R | Promise<R>;
+    /**
+     * Returns a reader over the bytes previously written under `id`, or `undefined` if no entry
+     * exists.
+     *
+     * @param id - Identifier supplied to a prior {@link ByteStore.write} call.
+     * @returns A reader over the stored bytes, `undefined`, or a `Promise` of either.
+     */
+    read(id: string): R | undefined | Promise<R | undefined>;
+    /**
+     * Removes the entry under `id`.
+     *
+     * @param id - Identifier whose entry should be removed.
+     * @returns `true` if an entry existed and was removed; `false` otherwise (or a `Promise` of one).
+     */
+    delete(id: string): boolean | Promise<boolean>;
+}
+/**
+ * A {@link ByteStore} that hands out line-indexed text readers ({@link @nhtio/adk!SpoolReader}).
+ *
+ * @remarks
+ * The store backing tool-output artifacts. Stored bytes are decoded as UTF-8 text for line-oriented
+ * reads; binary input is stored byte-faithfully but `SpoolReader.readAll()` interprets it as text,
+ * so opaque binary belongs in a {@link MediaStore} / `Media`, not here.
+ */
+export type SpoolStore = ByteStore<SpoolReader>;
+/**
+ * A {@link ByteStore} that hands out binary-streamed readers ({@link @nhtio/adk!MediaReader}).
+ *
+ * @remarks
+ * The store backing persisted media bytes. Stored bytes are opaque and replayable via
+ * `MediaReader.stream()`; no text decoding is implied.
+ */
+export type MediaStore = ByteStore<MediaReader>;
+/**
+ * Validator schema used to validate a {@link ByteStore} value.
+ *
+ * @remarks
+ * Because `ByteStore` is a structural interface with no associated constructor, validation is
+ * duck-typed: the value must be non-null with `write`, `read`, and `delete` present as callable
+ * properties. Arity is not enforced — implementations may add optional parameters beyond the
+ * contract. The reader type `R` cannot be checked structurally here; conformance of the reader is
+ * the caller's concern at the point of use.
+ */
+export declare const byteStoreSchema: import("@nhtio/validation").AnySchema<any>;
+/**
+ * Returns `true` if `value` implements the {@link ByteStore} interface.
+ *
+ * @remarks
+ * Duck-typed: checks that `value` is non-null with `write`, `read`, and `delete` as callable
+ * functions. Does not use `instanceof` — there is no `ByteStore` constructor.
+ *
+ * @param value - The value to test.
+ * @returns `true` when `value` conforms to the {@link ByteStore} interface.
+ */
+export declare const implementsByteStore: <R = unknown>(value: unknown) => value is ByteStore<R>;

package/lib/contracts/dispatch_context.d.ts

@@ -5,10 +5,14 @@ import type { Tool } from "../classes/tool";
 import type { Memory } from "../classes/memory";
 import type { Message } from "../classes/message";
 import type { Thought } from "../classes/thought";
+import type { SpoolReader } from "./spool_reader";
+import type { MediaReader } from "./media_reader";
 import type { ToolCall } from "../classes/tool_call";
 import type { Retrievable } from "../classes/retrievable";
 import type { DispatchContextHookRegistrations } from "../types/dispatch_context";
 import type { EmitMessageFn, EmitThoughtFn, EmitToolCallFn, EmitToolExecutionStartFn, EmitToolExecutionEndFn, OpenGateFn } from "../types/turn_runner";
+/** Payload accepted by the byte-persistence conduits — text, raw bytes, or a stream. */
+export type ConduitBytes = string | Uint8Array | ReadableStream<Uint8Array>;
 /** Retrieves memories for an LLM execution context. */
 export type DispatchMemoryRetrievalFn = (ctx: DispatchContext) => Memory[] | Promise<Memory[]>;
 /** Retrieves messages for an LLM execution context. */
@@ -59,6 +63,20 @@ export type DispatchToolCallStoreFn = (ctx: DispatchContext, v: ToolCall) => voi
 export type DispatchToolCallMutateFn = (ctx: DispatchContext, v: ToolCall) => void | Promise<void>;
 /** Removes a tool call by ID (LLM execution context variant). */
 export type DispatchToolCallDeleteFn = (ctx: DispatchContext, id: string) => void | Promise<void>;
+/**
+ * Persists tool-generated media bytes into consumer storage and returns a {@link @nhtio/adk!MediaReader}
+ * (LLM execution context variant). Unlike the `store*` mutation callbacks this returns a value and
+ * does NOT add anything to the turn Sets — the handler builds a {@link @nhtio/adk!Media} from the reader
+ * and persists it via `storeMessage`/`storeToolCall` separately.
+ */
+export type DispatchMediaBytesStoreFn = (ctx: DispatchContext, id: string, bytes: ConduitBytes) => MediaReader | Promise<MediaReader>;
+/**
+ * Persists extracted retrievable text bytes into consumer storage and returns a
+ * {@link @nhtio/adk!SpoolReader} (LLM execution context variant). The handler wraps the reader in a
+ * {@link @nhtio/adk!SpooledArtifact} for `new Retrievable({ content })` and persists the record via
+ * `storeRetrievable` separately. Returns a value; does NOT touch the turn Sets.
+ */
+export type DispatchRetrievableBytesStoreFn = (ctx: DispatchContext, id: string, bytes: ConduitBytes) => SpoolReader | Promise<SpoolReader>;
 /**
  * Plain input object supplied to {@link DispatchContext} at construction time.
  *
@@ -139,6 +157,10 @@ export interface RawDispatchContext {
     mutateToolCall: DispatchToolCallMutateFn;
     /** Removes a tool call by ID. */
     deleteToolCall: DispatchToolCallDeleteFn;
+    /** Persists tool-generated media bytes; returns a `MediaReader`. */
+    storeMediaBytes: DispatchMediaBytesStoreFn;
+    /** Persists extracted retrievable text bytes; returns a `SpoolReader`. */
+    storeRetrievableBytes: DispatchRetrievableBytesStoreFn;
     /** Optional hook registrations for emit events. */
     hooks?: DispatchContextHookRegistrations;
     /** Optional gate suspension function. When absent, `waitFor` rejects with {@link @nhtio/adk!E_LLM_EXECUTION_GATE_NOT_SUPPORTED}. */
@@ -330,6 +352,28 @@ export declare class DispatchContext {
     readonly mutateToolCall: (v: ToolCall) => Promise<void>;
     /** Removes a tool call from the local Set and persistence layer by ID. */
     readonly deleteToolCall: (id: string) => Promise<void>;
+    /**
+     * Persists tool-generated media bytes into consumer storage and returns a {@link @nhtio/adk!MediaReader}.
+     *
+     * @remarks
+     * This is a low-level persistence conduit, NOT a mutation: it does not add to `turnMessages`/
+     * `turnToolCalls` or fire a `stored*` hook. The handler builds a {@link @nhtio/adk!Media} from the
+     * returned reader (`Media.toolGenerated({ reader })`) and stores the owning primitive — a
+     * {@link @nhtio/adk!Message} attachment or {@link @nhtio/adk!ToolCall} result — via the relevant
+     * `store*` method separately. Persisting bytes without storing the primitive means the framework
+     * never sees the media.
+     */
+    readonly storeMediaBytes: (id: string, bytes: ConduitBytes) => MediaReader | Promise<MediaReader>;
+    /**
+     * Persists extracted retrievable text bytes into consumer storage and returns a
+     * {@link @nhtio/adk!SpoolReader}.
+     *
+     * @remarks
+     * Low-level persistence conduit, same posture as {@link DispatchContext.storeMediaBytes}: returns a
+     * value, touches no Sets, fires no hook. Wrap the reader in a {@link @nhtio/adk!SpooledArtifact} and
+     * pass it as `Retrievable.content`, then persist the record via {@link DispatchContext.storeRetrievable}.
+     */
+    readonly storeRetrievableBytes: (id: string, bytes: ConduitBytes) => SpoolReader | Promise<SpoolReader>;
     /** Emits a `message` hook; fires registered handlers synchronously. */
     readonly emitMessage: EmitMessageFn;
     /** Emits a `thought` hook; fires registered handlers synchronously. */

package/lib/contracts/turn_runner_config.d.ts

@@ -1,7 +1,7 @@
 import { Tool } from "../classes/tool";
 import type { TurnPipelineMiddlewareFn } from "../types/turn_runner";
 import type { DispatchPipelineMiddlewareFn, DispatchExecutorFn } from "../types/dispatch_runner";
-import type { MemoryRetrievalFn, MessageRetrievalFn, ThoughtRetrievalFn, ToolCallRetrievalFn, ToolsRetrievalFn, StandingInstructionsRefreshFn, StandingInstructionStoreFn, StandingInstructionMutateFn, StandingInstructionDeleteFn, MemoryStoreFn, MemoryMutateFn, MemoryDeleteFn, RetrievableRetrievalFn, RetrievableStoreFn, RetrievableMutateFn, RetrievableDeleteFn, MessageStoreFn, MessageMutateFn, MessageDeleteFn, ThoughtStoreFn, ThoughtMutateFn, ThoughtDeleteFn, ToolCallStoreFn, ToolCallMutateFn, ToolCallDeleteFn } from "./turn_runner_context";
+import type { MemoryRetrievalFn, MessageRetrievalFn, ThoughtRetrievalFn, ToolCallRetrievalFn, ToolsRetrievalFn, StandingInstructionsRefreshFn, StandingInstructionStoreFn, StandingInstructionMutateFn, StandingInstructionDeleteFn, MemoryStoreFn, MemoryMutateFn, MemoryDeleteFn, RetrievableRetrievalFn, RetrievableStoreFn, RetrievableMutateFn, RetrievableDeleteFn, MessageStoreFn, MessageMutateFn, MessageDeleteFn, ThoughtStoreFn, ThoughtMutateFn, ThoughtDeleteFn, ToolCallStoreFn, ToolCallMutateFn, ToolCallDeleteFn, MediaBytesStoreFn, RetrievableBytesStoreFn } from "./turn_runner_context";
 /**
  * Configuration supplied to {@link @nhtio/adk!TurnRunner} at construction time.
  *
@@ -69,6 +69,10 @@ export interface TurnRunnerConfig {
     mutateToolCallCallback: ToolCallMutateFn;
     /** Removes a tool call from the persistence layer by ID. */
     deleteToolCallCallback: ToolCallDeleteFn;
+    /** Persists tool-generated media bytes into consumer storage; returns a `MediaReader`. */
+    storeMediaBytesCallback: MediaBytesStoreFn;
+    /** Persists extracted retrievable text bytes into consumer storage; returns a `SpoolReader`. */
+    storeRetrievableBytesCallback: RetrievableBytesStoreFn;
     /** Baseline tools available on every turn. Middleware may trim or extend this per-turn via `ctx.tools`. Defaults to `[]`. */
     tools?: Tool[];
     /** Turn-level input middleware, executed in order against the {@link @nhtio/adk!TurnContext} before the LLM dispatch. Defaults to `[]`. */

package/lib/contracts/turn_runner_context.d.ts

@@ -4,7 +4,10 @@ import type { Tool } from "../classes/tool";
 import type { Memory } from "../classes/memory";
 import type { Message } from "../classes/message";
 import type { Thought } from "../classes/thought";
+import type { SpoolReader } from "./spool_reader";
+import type { MediaReader } from "./media_reader";
 import type { ToolCall } from "../classes/tool_call";
+import type { ConduitBytes } from "./dispatch_context";
 import type { Retrievable } from "../classes/retrievable";
 import type { ToolRegistry } from "../classes/tool_registry";
 import type { EmitMessageFn, EmitThoughtFn, EmitToolCallFn, EmitToolExecutionEndFn, EmitToolExecutionStartFn, OpenGateFn } from "../types/turn_runner";
@@ -149,6 +152,16 @@ export type ToolCallStoreFn = (ctx: TurnContext, v: ToolCall) => void | Promise<
 export type ToolCallMutateFn = (ctx: TurnContext, v: ToolCall) => void | Promise<void>;
 /** Removes a tool call from the persistence layer by ID. */
 export type ToolCallDeleteFn = (ctx: TurnContext, id: string) => void | Promise<void>;
+/**
+ * Persists tool-generated media bytes into consumer storage and returns a {@link @nhtio/adk!MediaReader}.
+ * A byte-persistence conduit, not a mutation — returns a value and touches no turn state.
+ */
+export type MediaBytesStoreFn = (ctx: TurnContext, id: string, bytes: ConduitBytes) => MediaReader | Promise<MediaReader>;
+/**
+ * Persists extracted retrievable text bytes into consumer storage and returns a
+ * {@link @nhtio/adk!SpoolReader}. A byte-persistence conduit, not a mutation.
+ */
+export type RetrievableBytesStoreFn = (ctx: TurnContext, id: string, bytes: ConduitBytes) => SpoolReader | Promise<SpoolReader>;
 /**
  * The validated, strongly-typed context object threaded through every middleware step in a
  * single agent turn.
@@ -250,6 +263,18 @@ export declare class TurnContext {
     readonly mutateToolCall: (v: ToolCall) => void | Promise<void>;
     /** Removes a tool call from the persistence layer by ID. */
     readonly deleteToolCall: (id: string) => void | Promise<void>;
+    /**
+     * Persists tool-generated media bytes into consumer storage and returns a {@link @nhtio/adk!MediaReader}.
+     * Low-level conduit — returns a value, touches no turn state; build a {@link @nhtio/adk!Media} from the
+     * reader and persist the owning primitive separately.
+     */
+    readonly storeMediaBytes: (id: string, bytes: ConduitBytes) => MediaReader | Promise<MediaReader>;
+    /**
+     * Persists extracted retrievable text bytes into consumer storage and returns a
+     * {@link @nhtio/adk!SpoolReader}. Wrap it in a {@link @nhtio/adk!SpooledArtifact} for `Retrievable.content`
+     * and persist the record via {@link TurnContext.storeRetrievable} separately.
+     */
+    readonly storeRetrievableBytes: (id: string, bytes: ConduitBytes) => SpoolReader | Promise<SpoolReader>;
     /** Emits a `message` event on the runner; may be called at any point during the turn. */
     readonly emitMessage: EmitMessageFn;
     /** Emits a `thought` event on the runner; may be called at any point during the turn. */