@nhtio/adk 0.1.0-master-f0aa531d

package/turn_runner-y7eyEcJH.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn_runner-y7eyEcJH.mjs","names":["#id","#turnId","#reason","#payload","#createdAt","#settled","#schema","#controller","#promise","#resolve","#reject","#config","#inputRunner","#outputRunner","#functionalEmitter","#observabilityEmitter"],"sources":["../src/lib/classes/turn_gate.ts","../src/lib/contracts/turn_runner_config.ts","../src/lib/turn_runner.ts"],"sourcesContent":["import { DateTime } from 'luxon'\nimport { validator } from '@nhtio/validation'\nimport { validateOrThrow } from '../utils/validation'\nimport { isInstanceOf, isError, isObject } from '../utils/guards'\nimport {\n  E_TURN_GATE_ABORTED,\n  E_TURN_GATE_TIMEOUT,\n  E_INVALID_TURN_GATE_RESOLUTION,\n  E_INVALID_INITIAL_TURN_GATE_VALUE,\n} from '../exceptions/runtime'\nimport type { Schema } from '@nhtio/validation'\n\n/**\n * Plain input object supplied to {@link TurnGate} at construction time.\n *\n * @remarks\n * `turnId` and `abortSignal` are injected by the runner — callers constructing a gate via\n * `ctx.waitFor()` never supply them directly.\n *\n * `abortSignal` is `AbortSignal` (not `AbortController`) because the gate reacts to turn-level\n * cancellation but cannot trigger it. The gate owns its own internal `AbortController` for\n * `gate.abort()`.\n */\nexport interface RawTurnGate {\n  /** Stable unique identifier for this gate. */\n  id: string\n  /** The ID of the turn that opened this gate. */\n  turnId: string\n  /** Human-readable label describing why this gate was opened (e.g. `'tool_approval'`). */\n  reason: string\n  /** Arbitrary data supplied to the gate opener; passed through to `turnGateOpen` listeners. */\n  payload: unknown\n  /** Optional validator schema for the resolution value. When present, `resolve()` validates before settling. */\n  schema?: Schema\n  /** Optional timeout in milliseconds. When elapsed the gate self-rejects with {@link @nhtio/adk!E_TURN_GATE_TIMEOUT}. */\n  timeout?: number\n  /** The turn's abort signal. When fired the gate self-rejects with {@link @nhtio/adk!E_TURN_GATE_ABORTED}. */\n  abortSignal?: AbortSignal\n  /** When this gate was created. */\n  createdAt: string | number | Date | DateTime\n}\n\n/**\n * Fully-resolved {@link RawTurnGate} after schema validation.\n *\n * @internal\n */\ninterface ResolvedTurnGate {\n  id: string\n  turnId: string\n  reason: string\n  payload: unknown\n  schema?: Schema\n  timeout?: number\n  abortSignal?: AbortSignal\n  createdAt: DateTime\n}\n\n/**\n * Validator schema used to validate a {@link RawTurnGate} before constructing a {@link TurnGate}.\n *\n * @remarks\n * - `schema` and `abortSignal` are validated as opaque passthrough values.\n * - `timeout` must be a positive integer when provided.\n */\nconst rawTurnGateSchema = validator.object<RawTurnGate>({\n  id: validator.string().required(),\n  turnId: validator.string().required(),\n  reason: validator.string().required(),\n  payload: validator.any().required(),\n  schema: validator\n    .any()\n    .custom((value, helpers) => {\n      if (value === undefined || value === null) return undefined\n      if (typeof (value as any).validate === 'function') return value\n      return helpers.error('any.invalid')\n    })\n    .optional(),\n  timeout: validator.number().integer().min(1).optional(),\n  abortSignal: validator\n    .any()\n    .custom((value, helpers) => {\n      if (value === undefined || value === null) return undefined\n      // eslint-disable-next-line adk/use-is-instance-of -- native built-in; AbortSignal cross-realm is handled by the duck-type fallback below\n      if (typeof AbortSignal !== 'undefined' && value instanceof AbortSignal) return value\n      if (\n        isObject(value) &&\n        typeof (value as any).aborted === 'boolean' &&\n        typeof (value as any).addEventListener === 'function'\n      ) {\n        return value\n      }\n      return helpers.error('any.invalid')\n    })\n    .optional(),\n  createdAt: validator.datetime().required(),\n})\n\n/**\n * A cooperative suspension gate that blocks a turn's middleware pipeline until resolved, rejected,\n * aborted, or timed out.\n *\n * @typeParam T - The expected type of the resolution value.\n *\n * @remarks\n * Created exclusively via `ctx.waitFor()` — middleware never constructs a gate directly.\n * The gate emits `turnGateOpen` on the runner's observability bus at creation time and\n * `turnGateClosed` when it settles.\n *\n * Resolution is validated against an optional schema before the internal promise is settled.\n * A validation failure throws {@link @nhtio/adk!E_INVALID_TURN_GATE_RESOLUTION} **synchronously in the\n * caller's context** — the promise is NOT settled and the gate remains open.\n */\nexport class TurnGate<T = unknown> {\n  /**\n   * Validator schema that accepts a {@link RawTurnGate} object.\n   *\n   * @remarks\n   * Reusable fragment for any schema that needs to validate or nest a gate entry.\n   */\n  public static schema = rawTurnGateSchema\n\n  /**\n   * Returns `true` if `value` is a {@link TurnGate} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is a {@link TurnGate} instance.\n   */\n  public static isTurnGate(value: unknown): value is TurnGate {\n    return isInstanceOf(value, 'TurnGate', TurnGate)\n  }\n\n  declare readonly id: string\n  declare readonly turnId: string\n  declare readonly reason: string\n  declare readonly payload: unknown\n  declare readonly createdAt: DateTime\n  declare readonly isSettled: boolean\n\n  #id: string\n  #turnId: string\n  #reason: string\n  #payload: unknown\n  #createdAt: DateTime\n  #settled: boolean\n  #schema: Schema | undefined\n  #controller: AbortController\n  #resolve!: (value: T) => void\n  #reject!: (reason: unknown) => void\n  #promise: Promise<T>\n\n  /**\n   * @param raw - The raw gate input validated against `rawTurnGateSchema`.\n   * @throws {@link @nhtio/adk!E_INVALID_INITIAL_TURN_GATE_VALUE} when `raw` does not satisfy the schema.\n   */\n  constructor(raw: RawTurnGate) {\n    let resolved: ResolvedTurnGate\n    try {\n      resolved = validateOrThrow<ResolvedTurnGate>(rawTurnGateSchema, raw, true)\n    } catch (err) {\n      throw new E_INVALID_INITIAL_TURN_GATE_VALUE({ cause: isError(err) ? err : undefined })\n    }\n\n    this.#id = resolved.id\n    this.#turnId = resolved.turnId\n    this.#reason = resolved.reason\n    this.#payload = resolved.payload\n    this.#createdAt = resolved.createdAt\n    this.#settled = false\n    this.#schema = resolved.schema\n    this.#controller = new AbortController()\n\n    this.#promise = new Promise<T>((resolve, reject) => {\n      this.#resolve = resolve\n      this.#reject = reject\n    })\n\n    // Wire the internal abort controller\n    const onAbort = () => {\n      if (!this.#settled) {\n        this.#settled = true\n        this.#reject(new E_TURN_GATE_ABORTED())\n      }\n    }\n\n    this.#controller.signal.addEventListener('abort', onAbort, { once: true })\n\n    // Wire the external turn abort signal\n    if (resolved.abortSignal) {\n      if (resolved.abortSignal.aborted) {\n        // Already aborted — reject immediately after construction\n        queueMicrotask(() => onAbort())\n      } else {\n        resolved.abortSignal.addEventListener('abort', onAbort, { once: true })\n        // Clean up the external listener once the gate settles via another path\n        this.#promise.then(\n          () => resolved.abortSignal!.removeEventListener('abort', onAbort),\n          () => resolved.abortSignal!.removeEventListener('abort', onAbort)\n        )\n      }\n    }\n\n    // Wire the timeout\n    if (resolved.timeout !== undefined) {\n      const timer = setTimeout(() => {\n        if (!this.#settled) {\n          this.#settled = true\n          this.#reject(new E_TURN_GATE_TIMEOUT())\n        }\n      }, resolved.timeout)\n\n      this.#promise.then(\n        () => clearTimeout(timer),\n        () => clearTimeout(timer)\n      )\n    }\n\n    Object.defineProperties(this, {\n      id: {\n        get: () => this.#id,\n        enumerable: true,\n        configurable: false,\n      },\n      turnId: {\n        get: () => this.#turnId,\n        enumerable: true,\n        configurable: false,\n      },\n      reason: {\n        get: () => this.#reason,\n        enumerable: true,\n        configurable: false,\n      },\n      payload: {\n        get: () => this.#payload,\n        enumerable: true,\n        configurable: false,\n      },\n      createdAt: {\n        get: () => this.#createdAt,\n        enumerable: true,\n        configurable: false,\n      },\n      isSettled: {\n        get: () => this.#settled,\n        enumerable: true,\n        configurable: false,\n      },\n    })\n  }\n\n  /**\n   * Resolves the gate with `value`, unblocking the awaiting middleware.\n   *\n   * @remarks\n   * If a schema was provided at construction, `value` is validated synchronously before the\n   * promise is settled. A validation failure throws {@link @nhtio/adk!E_INVALID_TURN_GATE_RESOLUTION}\n   * in the caller's context — the promise is NOT settled and the gate remains open.\n   *\n   * No-ops if the gate is already settled.\n   *\n   * @param value - The resolution value. Must satisfy the gate's schema when one was provided.\n   * @throws {@link @nhtio/adk!E_INVALID_TURN_GATE_RESOLUTION} when `value` fails schema validation.\n   */\n  resolve(value: unknown): void {\n    if (this.#settled) return\n    if (this.#schema !== undefined) {\n      try {\n        value = validateOrThrow(this.#schema, value, true)\n      } catch (err) {\n        throw new E_INVALID_TURN_GATE_RESOLUTION({\n          cause: isError(err) ? err : undefined,\n        })\n      }\n    }\n    this.#settled = true\n    this.#resolve(value as T)\n  }\n\n  /**\n   * Rejects the gate with `error`, unblocking the awaiting middleware with a rejection.\n   *\n   * @remarks\n   * No-ops if the gate is already settled.\n   *\n   * @param error - The rejection reason.\n   */\n  reject(error: Error): void {\n    if (this.#settled) return\n    this.#settled = true\n    this.#reject(error)\n  }\n\n  /**\n   * Aborts the gate by firing the internal `AbortController`, which rejects the promise with\n   * {@link @nhtio/adk!E_TURN_GATE_ABORTED}.\n   *\n   * @remarks\n   * No-ops if the gate is already settled. Distinct from the turn-level abort signal — this\n   * allows callers to cancel a specific gate without aborting the whole turn.\n   */\n  abort(): void {\n    if (this.#settled) return\n    this.#controller.abort()\n  }\n\n  /**\n   * Returns the internal promise. Called by `ctx.waitFor()` to block the middleware pipeline.\n   *\n   * @internal\n   */\n  _promise(): Promise<T> {\n    return this.#promise\n  }\n}\n","import { Tool } from '../classes/tool'\nimport { validator } from '@nhtio/validation'\nimport type { TurnPipelineMiddlewareFn } from '../types/turn_runner'\nimport type { DispatchPipelineMiddlewareFn, DispatchExecutorFn } from '../types/dispatch_runner'\nimport type {\n  MemoryRetrievalFn,\n  MessageRetrievalFn,\n  ThoughtRetrievalFn,\n  ToolCallRetrievalFn,\n  ToolsRetrievalFn,\n  StandingInstructionsRefreshFn,\n  StandingInstructionStoreFn,\n  StandingInstructionMutateFn,\n  StandingInstructionDeleteFn,\n  MemoryStoreFn,\n  MemoryMutateFn,\n  MemoryDeleteFn,\n  RetrievableRetrievalFn,\n  RetrievableStoreFn,\n  RetrievableMutateFn,\n  RetrievableDeleteFn,\n  MessageStoreFn,\n  MessageMutateFn,\n  MessageDeleteFn,\n  ThoughtStoreFn,\n  ThoughtMutateFn,\n  ThoughtDeleteFn,\n  ToolCallStoreFn,\n  ToolCallMutateFn,\n  ToolCallDeleteFn,\n} from './turn_runner_context'\n\n/**\n * Configuration supplied to {@link @nhtio/adk!TurnRunner} at construction time.\n *\n * @remarks\n * Validated against `turnRunnerConfigSchema` at construction — a misconfigured runner throws\n * immediately rather than failing on the first turn.\n *\n * All fetch and mutation callbacks are required: they are injected into each {@link @nhtio/adk!TurnContext}\n * so middleware can call fetch, refresh, and persistence methods directly on the context without\n * coupling to the runner.\n *\n * `tools` is optional at the caller level and defaults to `[]` after schema resolution — a runner\n * with no baseline tools is valid.\n */\nexport interface TurnRunnerConfig {\n  /** Performs the LLM API/SDK call for each iteration of the dispatch loop; receives the active {@link @nhtio/adk!DispatchContext} and an {@link @nhtio/adk!DispatchExecutorHelpers} object for managing per-id stream state. */\n  executorCallback: DispatchExecutorFn\n  /** Called once per turn to supply memories; receives the active {@link @nhtio/adk!TurnContext}. */\n  fetchMemoriesCallback: MemoryRetrievalFn\n  /** Called once per turn to supply conversation history; receives the active {@link @nhtio/adk!TurnContext}. */\n  fetchMessagesCallback: MessageRetrievalFn\n  /** Called once per turn to supply thought traces; receives the active {@link @nhtio/adk!TurnContext}. */\n  fetchThoughtsCallback: ThoughtRetrievalFn\n  /** Called once per turn to supply tool call records; receives the active {@link @nhtio/adk!TurnContext}. */\n  fetchToolCallsCallback: ToolCallRetrievalFn\n  /** Called to supply available tools; receives the active {@link @nhtio/adk!TurnContext}. */\n  fetchToolsCallback: ToolsRetrievalFn\n  /** Called to refresh and return standing instructions; receives the active {@link @nhtio/adk!TurnContext}. */\n  refreshStandingInstructionsCallback: StandingInstructionsRefreshFn\n  /** Persists a new standing instruction. */\n  storeStandingInstructionCallback: StandingInstructionStoreFn\n  /** Updates an existing standing instruction in the persistence layer. */\n  mutateStandingInstructionCallback: StandingInstructionMutateFn\n  /** Removes a standing instruction from the persistence layer. */\n  deleteStandingInstructionCallback: StandingInstructionDeleteFn\n  /** Persists a new memory. */\n  storeMemoryCallback: MemoryStoreFn\n  /** Updates an existing memory in the persistence layer. */\n  mutateMemoryCallback: MemoryMutateFn\n  /** Removes a memory from the persistence layer by ID. */\n  deleteMemoryCallback: MemoryDeleteFn\n  /** Called once per turn to supply retrievable (RAG) records; receives the active {@link @nhtio/adk!TurnContext}. */\n  fetchRetrievablesCallback: RetrievableRetrievalFn\n  /** Persists a new retrievable record. */\n  storeRetrievableCallback: RetrievableStoreFn\n  /** Updates an existing retrievable record in the persistence layer. */\n  mutateRetrievableCallback: RetrievableMutateFn\n  /** Removes a retrievable record from the persistence layer by ID. */\n  deleteRetrievableCallback: RetrievableDeleteFn\n  /** Persists a new message. */\n  storeMessageCallback: MessageStoreFn\n  /** Updates an existing message in the persistence layer. */\n  mutateMessageCallback: MessageMutateFn\n  /** Removes a message from the persistence layer by ID. */\n  deleteMessageCallback: MessageDeleteFn\n  /** Persists a new thought. */\n  storeThoughtCallback: ThoughtStoreFn\n  /** Updates an existing thought in the persistence layer. */\n  mutateThoughtCallback: ThoughtMutateFn\n  /** Removes a thought from the persistence layer by ID. */\n  deleteThoughtCallback: ThoughtDeleteFn\n  /** Persists a new tool call. */\n  storeToolCallCallback: ToolCallStoreFn\n  /** Updates an existing tool call in the persistence layer. */\n  mutateToolCallCallback: ToolCallMutateFn\n  /** Removes a tool call from the persistence layer by ID. */\n  deleteToolCallCallback: ToolCallDeleteFn\n  /** Baseline tools available on every turn. Middleware may trim or extend this per-turn via `ctx.tools`. Defaults to `[]`. */\n  tools?: Tool[]\n  /** Turn-level input middleware, executed in order against the {@link @nhtio/adk!TurnContext} before the LLM dispatch. Defaults to `[]`. */\n  turnInputPipeline?: TurnPipelineMiddlewareFn[]\n  /** Turn-level output middleware, executed in order against the {@link @nhtio/adk!TurnContext} after the LLM dispatch resolves successfully. Defaults to `[]`. */\n  turnOutputPipeline?: TurnPipelineMiddlewareFn[]\n  /** LLM-iteration input middleware, executed in order against the {@link @nhtio/adk!DispatchContext} before the executor on each iteration. Defaults to `[]`. */\n  dispatchInputPipeline?: DispatchPipelineMiddlewareFn[]\n  /** LLM-iteration output middleware, executed in order against the {@link @nhtio/adk!DispatchContext} after the executor on each iteration. Defaults to `[]`. */\n  dispatchOutputPipeline?: DispatchPipelineMiddlewareFn[]\n}\n\n/**\n * Fully-resolved {@link TurnRunnerConfig} after schema validation.\n *\n * @remarks\n * All optional fields are guaranteed present (e.g. `tools` defaults to `[]`). The runner stores\n * this type internally so field access never needs to guard for undefined.\n */\nexport type ResolvedTurnRunnerConfig = Required<TurnRunnerConfig>\n\n/**\n * Validator schema used to validate a {@link TurnRunnerConfig} at {@link @nhtio/adk!TurnRunner} construction time.\n *\n * @remarks\n * Validates that all callbacks are functions of the correct arity, and that `tools` — when\n * provided — is an array of valid {@link @nhtio/adk!Tool} instances. Defaults `tools` to `[]`.\n *\n * Throws {@link @nhtio/adk!E_INVALID_TURN_RUNNER_CONFIG} (via the {@link @nhtio/adk!TurnRunner} constructor) when\n * validation fails.\n */\nexport const turnRunnerConfigSchema = validator.object<TurnRunnerConfig>({\n  executorCallback: validator.function().required(),\n  fetchMemoriesCallback: validator.function().arity(1).required(),\n  fetchMessagesCallback: validator.function().arity(1).required(),\n  fetchThoughtsCallback: validator.function().arity(1).required(),\n  fetchToolCallsCallback: validator.function().arity(1).required(),\n  fetchToolsCallback: validator.function().arity(1).required(),\n  refreshStandingInstructionsCallback: validator.function().arity(1).required(),\n  storeStandingInstructionCallback: validator.function().arity(2).required(),\n  mutateStandingInstructionCallback: validator.function().arity(2).required(),\n  deleteStandingInstructionCallback: validator.function().arity(2).required(),\n  storeMemoryCallback: validator.function().arity(2).required(),\n  mutateMemoryCallback: validator.function().arity(2).required(),\n  deleteMemoryCallback: validator.function().arity(2).required(),\n  fetchRetrievablesCallback: validator.function().arity(1).required(),\n  storeRetrievableCallback: validator.function().arity(2).required(),\n  mutateRetrievableCallback: validator.function().arity(2).required(),\n  deleteRetrievableCallback: validator.function().arity(2).required(),\n  storeMessageCallback: validator.function().arity(2).required(),\n  mutateMessageCallback: validator.function().arity(2).required(),\n  deleteMessageCallback: validator.function().arity(2).required(),\n  storeThoughtCallback: validator.function().arity(2).required(),\n  mutateThoughtCallback: validator.function().arity(2).required(),\n  deleteThoughtCallback: validator.function().arity(2).required(),\n  storeToolCallCallback: validator.function().arity(2).required(),\n  mutateToolCallCallback: validator.function().arity(2).required(),\n  deleteToolCallCallback: validator.function().arity(2).required(),\n  tools: validator\n    .array()\n    .items(\n      validator.any().custom((value: unknown, helpers: { error: (code: string) => unknown }) => {\n        if (Tool.isTool(value)) return value\n        return helpers.error('any.invalid')\n      })\n    )\n    .default([]),\n  turnInputPipeline: validator.array().items(validator.function()).default([]),\n  turnOutputPipeline: validator.array().items(validator.function()).default([]),\n  dispatchInputPipeline: validator.array().items(validator.function()).default([]),\n  dispatchOutputPipeline: validator.array().items(validator.function()).default([]),\n})\n","import { DateTime } from 'luxon'\nimport { Middleware } from '@nhtio/middleware'\nimport { TurnGate } from './classes/turn_gate'\nimport { DispatchRunner } from './dispatch_runner'\nimport { ToolRegistry } from './classes/tool_registry'\nimport { isInstanceOf, isError } from './utils/guards'\nimport { TypedEventEmitter } from '@nhtio/tiny-typed-emitter'\nimport { passesSchema, validateOrThrow } from './utils/validation'\nimport { turnRunnerConfigSchema } from './contracts/turn_runner_config'\nimport { TurnContext, RawTurnContext } from './contracts/turn_runner_context'\nimport {\n  E_INVALID_TURN_RUNNER_CONFIG,\n  E_INPUT_PIPELINE_ERROR,\n  E_OUTPUT_PIPELINE_ERROR,\n  E_PIPELINE_SHORT_CIRCUITED,\n} from './exceptions/runtime'\nimport type { Runner } from '@nhtio/middleware'\nimport type { RawTurnGate } from './classes/turn_gate'\nimport type { ResolvedTurnRunnerConfig, TurnRunnerConfig } from './contracts/turn_runner_config'\nimport type {\n  OpenGateFn,\n  TurnEvents,\n  TurnEvent,\n  TurnEventListener,\n  TurnPipelineMiddlewareFn,\n  TurnObservabilityEvents,\n  TurnObservabilityEvent,\n  TurnObservabilityEventListener,\n} from './types/turn_runner'\n\nexport type {\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} from './types/turn_runner'\n\n/**\n * Executes a single agent turn through paired input and output middleware pipelines.\n *\n * @remarks\n * Construction validates `config` eagerly and throws {@link @nhtio/adk!E_INVALID_TURN_RUNNER_CONFIG} if it\n * does not satisfy the schema — fail-fast so misconfiguration surfaces before any turn runs.\n *\n * Each call to {@link TurnRunner.run} threads a {@link @nhtio/adk!TurnContext} through the input pipeline,\n * invokes the model, then threads the result through the output pipeline. Middleware on each side\n * can read and mutate the context for pre- and post-processing (e.g. message normalisation, tool\n * call dispatch, response filtering).\n *\n * **Two event buses:**\n * - Functional bus (`on` / `off` / `once`): `message`, `thought`, `toolCall` — pipeline-affecting\n *   events that middleware raises throughout turn execution.\n * - Observability bus (`observe` / `unobserve` / `observeOnce`): `turnStart`, `turnEnd`,\n *   `turnGateOpen`, `turnGateClosed`, `error` — instrumentation-only events that monitor execution\n *   without participating in it.\n *\n * Streaming content is surfaced via `message` and `thought` events; tool call lifecycle via\n * `toolCall`; non-fatal pipeline errors via the observability `error` event; gate lifecycle via\n * `turnGateOpen` and `turnGateClosed` — all throughout execution.\n *\n * @example\n * ```ts\n * const runner = new TurnRunner({\n *   fetchMemoriesCallback: async (ctx) => memoryStore.query(ctx),\n *   fetchMessagesCallback: async (ctx) => messageStore.history(ctx),\n *   fetchThoughtsCallback: async (ctx) => thoughtStore.history(ctx),\n *   fetchToolCallsCallback: async (ctx) => toolCallStore.history(ctx),\n * })\n * // Functional bus — pipeline events\n * runner.on('message', (chunk) => process.stdout.write(chunk.aDelta))\n * // Observability bus — instrumentation\n * runner.observe('error', (err) => console.error(err.toString()))\n * runner.observe('turnStart', ({ turnId }) => console.log('turn started', turnId))\n * runner.observe('turnGateOpen', (gate) => {\n *   if (gate.reason === 'tool_approval') {\n *     gate.resolve(true) // approve immediately for this example\n *   }\n * })\n * await runner.run({\n *   turnAbortController: new AbortController(),\n *   systemPrompt: 'You are a helpful assistant.',\n *   standingInstructions: [],\n * })\n * ```\n */\nexport class TurnRunner {\n  /**\n   * Returns `true` if `value` is a {@link TurnRunner} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is a {@link TurnRunner} instance.\n   */\n  public static isTurnRunner(value: unknown): value is TurnRunner {\n    return isInstanceOf(value, 'TurnRunner', TurnRunner)\n  }\n\n  #config: ResolvedTurnRunnerConfig\n  #inputRunner: Runner<TurnPipelineMiddlewareFn>\n  #outputRunner: Runner<TurnPipelineMiddlewareFn>\n  #functionalEmitter: TypedEventEmitter<TurnEvents>\n  #observabilityEmitter: TypedEventEmitter<TurnObservabilityEvents>\n\n  /**\n   * @param config - Construction-time configuration validated against {@link turnRunnerConfigSchema}.\n   * @throws {@link @nhtio/adk!E_INVALID_TURN_RUNNER_CONFIG} when `config` does not satisfy the schema.\n   */\n  constructor(config: TurnRunnerConfig) {\n    const isValid = passesSchema(turnRunnerConfigSchema, config)\n    if (!isValid) {\n      throw new E_INVALID_TURN_RUNNER_CONFIG()\n    }\n    // Store the resolved config so optional fields (e.g. tools) are always present.\n    this.#config = validateOrThrow<ResolvedTurnRunnerConfig>(turnRunnerConfigSchema, config, true)\n    const turnInputPipeline = new Middleware<TurnPipelineMiddlewareFn>()\n    const turnOutputPipeline = new Middleware<TurnPipelineMiddlewareFn>()\n    const wrap =\n      (fn: TurnPipelineMiddlewareFn): TurnPipelineMiddlewareFn =>\n      (ctx, next) => {\n        // Skip downstream user middlewares once an abort has been signalled. The\n        // wrapper still calls next() so the pipeline reaches its terminal resolver\n        // (keeping the short-circuit detector quiet); the original middleware body\n        // does not run, so it has nothing to clean up.\n        if (ctx.aborted) return next()\n        return fn(ctx, next)\n      }\n    for (const fn of this.#config.turnInputPipeline) turnInputPipeline.add(wrap(fn))\n    for (const fn of this.#config.turnOutputPipeline) turnOutputPipeline.add(wrap(fn))\n    this.#inputRunner = turnInputPipeline.runner()\n    this.#outputRunner = turnOutputPipeline.runner()\n    this.#functionalEmitter = new TypedEventEmitter<TurnEvents>()\n    this.#observabilityEmitter = new TypedEventEmitter<TurnObservabilityEvents>()\n  }\n\n  // ── Functional bus ───────────────────────────────────────────────────────\n\n  /**\n   * Removes a previously registered functional listener for `event`.\n   *\n   * @param event - The event to stop listening to.\n   * @param listener - The listener function to remove.\n   * @returns `this` for chaining.\n   */\n  off<K>(event: TurnEvent<K>, listener: TurnEventListener<K>): this {\n    this.#functionalEmitter.off(event, listener)\n    return this\n  }\n\n  /**\n   * Registers a persistent functional listener for `event`.\n   *\n   * @param event - The event to listen to.\n   * @param listener - The function to call on each emission.\n   * @returns `this` for chaining.\n   */\n  on<K>(event: TurnEvent<K>, listener: TurnEventListener<K>): this {\n    this.#functionalEmitter.on(event, listener)\n    return this\n  }\n\n  /**\n   * Registers a one-time functional listener for `event` that is automatically removed after the\n   * first emission.\n   *\n   * @param event - The event to listen to.\n   * @param listener - The function to call on the next emission.\n   * @returns `this` for chaining.\n   */\n  once<K>(event: TurnEvent<K>, listener: TurnEventListener<K>): this {\n    this.#functionalEmitter.once(event, listener)\n    return this\n  }\n\n  // ── Observability bus ────────────────────────────────────────────────────\n\n  /**\n   * Removes a previously registered observability listener for `event`.\n   *\n   * @param event - The event to stop observing.\n   * @param listener - The listener function to remove.\n   * @returns `this` for chaining.\n   */\n  unobserve<K>(\n    event: TurnObservabilityEvent<K>,\n    listener: TurnObservabilityEventListener<K>\n  ): this {\n    this.#observabilityEmitter.off(event, listener)\n    return this\n  }\n\n  /**\n   * Registers a persistent observability listener for `event`.\n   *\n   * @remarks\n   * Use the observability bus (`observe` / `unobserve` / `observeOnce`) for instrumentation:\n   * turn lifecycle, gate lifecycle, and non-fatal errors. Use the functional bus (`on` / `off` /\n   * `once`) for pipeline-affecting events: `message`, `thought`, `toolCall`.\n   *\n   * @param event - The event to observe.\n   * @param listener - The function to call on each emission.\n   * @returns `this` for chaining.\n   */\n  observe<K>(event: TurnObservabilityEvent<K>, listener: TurnObservabilityEventListener<K>): this {\n    this.#observabilityEmitter.on(event, listener)\n    return this\n  }\n\n  /**\n   * Registers a one-time observability listener for `event` that is automatically removed after\n   * the first emission.\n   *\n   * @param event - The event to observe once.\n   * @param listener - The function to call on the next emission.\n   * @returns `this` for chaining.\n   */\n  observeOnce<K>(\n    event: TurnObservabilityEvent<K>,\n    listener: TurnObservabilityEventListener<K>\n  ): this {\n    this.#observabilityEmitter.once(event, listener)\n    return this\n  }\n\n  // ── Turn execution ───────────────────────────────────────────────────────\n\n  /**\n   * Executes a single agent turn against the provided raw context.\n   *\n   * @remarks\n   * Returns `Promise<void>` intentionally — all meaningful output surfaces via events, not return\n   * values. Register listeners before calling `run`: observability events (`turnStart`, `turnEnd`)\n   * bracket execution; functional events (`message`, `thought`, `toolCall`) fire throughout;\n   * observability `error` carries non-fatal pipeline failures; `turnGateOpen` and `turnGateClosed`\n   * fire when middleware suspends via `ctx.waitFor()`. Awaiting this method only tells you the\n   * pipeline has finished, not what it produced.\n   *\n   * Constructs a validated {@link @nhtio/adk!TurnContext} from `context` (throwing\n   * {@link @nhtio/adk!E_INVALID_TURN_CONTEXT} on failure), then runs the input middleware pipeline.\n   * Abort signals are silently swallowed.\n   *\n   * @param context - Raw input validated and wrapped into a {@link @nhtio/adk!TurnContext} before execution.\n   * @throws {@link @nhtio/adk!E_INVALID_TURN_CONTEXT} when `context` does not satisfy the schema.\n   */\n  async run(context: RawTurnContext): Promise<void> {\n    const abortController = context.turnAbortController ?? new AbortController()\n\n    // Forward declaration so openGate can reference turnContext.id before it is assigned.\n    let turnContextId: string\n\n    const openGate: OpenGateFn = <T>(raw: Omit<RawTurnGate, 'turnId' | 'abortSignal'>) => {\n      const gate = new TurnGate<T>({\n        ...raw,\n        turnId: turnContextId,\n        abortSignal: abortController.signal,\n      })\n      this.#observabilityEmitter.emit('turnGateOpen', gate)\n      const promise = gate._promise()\n      promise.then(\n        () => {\n          this.#observabilityEmitter.emit('turnGateClosed', {\n            gateId: gate.id,\n            turnId: gate.turnId,\n            result: 'resolved',\n            settledAt: DateTime.now(),\n          })\n        },\n        (err: unknown) => {\n          let result: 'rejected' | 'aborted' | 'timeout' = 'rejected'\n          if (isInstanceOf(err, 'E_TURN_GATE_ABORTED')) result = 'aborted'\n          else if (isInstanceOf(err, 'E_TURN_GATE_TIMEOUT')) result = 'timeout'\n          this.#observabilityEmitter.emit('turnGateClosed', {\n            gateId: gate.id,\n            turnId: gate.turnId,\n            result,\n            settledAt: DateTime.now(),\n          })\n        }\n      )\n      return promise\n    }\n\n    const tools = new ToolRegistry(this.#config.tools)\n\n    const turnContext = new TurnContext(\n      { ...context, turnAbortController: abortController },\n      {\n        fetchMemories: this.#config.fetchMemoriesCallback,\n        fetchMessages: this.#config.fetchMessagesCallback,\n        fetchThoughts: this.#config.fetchThoughtsCallback,\n        fetchToolCalls: this.#config.fetchToolCallsCallback,\n        fetchTools: this.#config.fetchToolsCallback,\n        refreshStandingInstructions: this.#config.refreshStandingInstructionsCallback,\n        storeStandingInstruction: this.#config.storeStandingInstructionCallback,\n        mutateStandingInstruction: this.#config.mutateStandingInstructionCallback,\n        deleteStandingInstruction: this.#config.deleteStandingInstructionCallback,\n        storeMemory: this.#config.storeMemoryCallback,\n        mutateMemory: this.#config.mutateMemoryCallback,\n        deleteMemory: this.#config.deleteMemoryCallback,\n        fetchRetrievables: this.#config.fetchRetrievablesCallback,\n        storeRetrievable: this.#config.storeRetrievableCallback,\n        mutateRetrievable: this.#config.mutateRetrievableCallback,\n        deleteRetrievable: this.#config.deleteRetrievableCallback,\n        storeMessage: this.#config.storeMessageCallback,\n        mutateMessage: this.#config.mutateMessageCallback,\n        deleteMessage: this.#config.deleteMessageCallback,\n        storeThought: this.#config.storeThoughtCallback,\n        mutateThought: this.#config.mutateThoughtCallback,\n        deleteThought: this.#config.deleteThoughtCallback,\n        storeToolCall: this.#config.storeToolCallCallback,\n        mutateToolCall: this.#config.mutateToolCallCallback,\n        deleteToolCall: this.#config.deleteToolCallCallback,\n        emitMessage: (content) => this.#functionalEmitter.emit('message', content),\n        emitThought: (content) => this.#functionalEmitter.emit('thought', content),\n        emitToolCall: (content) => this.#functionalEmitter.emit('toolCall', content),\n        emitToolExecutionStart: (event) =>\n          this.#observabilityEmitter.emit('toolExecutionStart', event),\n        emitToolExecutionEnd: (event) => this.#observabilityEmitter.emit('toolExecutionEnd', event),\n        openGate,\n        tools,\n      }\n    )\n\n    turnContextId = turnContext.id\n\n    const startedAt = DateTime.now()\n    this.#observabilityEmitter.emit('turnStart', { turnId: turnContext.id, startedAt })\n\n    const emitTurnEnd = () => {\n      const endedAt = DateTime.now()\n      this.#observabilityEmitter.emit('turnEnd', {\n        turnId: turnContext.id,\n        startedAt,\n        endedAt,\n        durationMs: endedAt.diff(startedAt).milliseconds,\n      })\n    }\n\n    // 1. Input pipeline\n    let inputFailed = false\n    let inputReached = false\n    await this.#inputRunner\n      .errorHandler(async (error) => {\n        if (!isError(error) || !isInstanceOf(error, 'AbortError')) {\n          inputFailed = true\n          const err = new E_INPUT_PIPELINE_ERROR({\n            cause: isError(error) ? error : undefined,\n          })\n          this.#observabilityEmitter.emit('error', err)\n        }\n      })\n      .finalHandler(async () => {\n        inputReached = true\n      })\n      .run((fn, next) => Promise.resolve(fn(turnContext, next)))\n\n    if (!inputReached && !inputFailed && !turnContext.aborted) {\n      inputFailed = true\n      const err = new E_PIPELINE_SHORT_CIRCUITED(['turn-input'])\n      this.#observabilityEmitter.emit('error', err)\n    }\n\n    if (inputFailed || turnContext.aborted) {\n      emitTurnEnd()\n      return\n    }\n\n    // 2. LLM execution dispatch\n    let dispatchFailed = false\n    try {\n      await DispatchRunner.dispatch({\n        source: turnContext,\n        executor: this.#config.executorCallback,\n        turnInputPipeline: this.#config.dispatchInputPipeline,\n        turnOutputPipeline: this.#config.dispatchOutputPipeline,\n        observers: {\n          dispatchStart: [\n            (e) => {\n              this.#observabilityEmitter.emit('dispatchStart', e)\n            },\n          ],\n          dispatchEnd: [\n            (e) => {\n              this.#observabilityEmitter.emit('dispatchEnd', e)\n            },\n          ],\n          iterationStart: [\n            (e) => {\n              this.#observabilityEmitter.emit('iterationStart', e)\n            },\n          ],\n          iterationEnd: [\n            (e) => {\n              this.#observabilityEmitter.emit('iterationEnd', e)\n            },\n          ],\n          log: [\n            (e) => {\n              this.#observabilityEmitter.emit('log', e)\n            },\n          ],\n        },\n      })\n    } catch (err) {\n      dispatchFailed = true\n      const wrapped = isInstanceOf(err, 'BaseException') ? (err as InstanceType<typeof Error>) : err\n      this.#observabilityEmitter.emit('error', wrapped as any)\n    }\n\n    if (dispatchFailed || turnContext.aborted) {\n      emitTurnEnd()\n      return\n    }\n\n    // 3. Output pipeline\n    let outputFailed = false\n    let outputReached = false\n    await this.#outputRunner\n      .errorHandler(async (error) => {\n        if (!isError(error) || !isInstanceOf(error, 'AbortError')) {\n          outputFailed = true\n          const err = new E_OUTPUT_PIPELINE_ERROR({\n            cause: isError(error) ? error : undefined,\n          })\n          this.#observabilityEmitter.emit('error', err)\n        }\n      })\n      .finalHandler(async () => {\n        outputReached = true\n      })\n      .run((fn, next) => Promise.resolve(fn(turnContext, next)))\n\n    if (!outputReached && !outputFailed && !turnContext.aborted) {\n      const err = new E_PIPELINE_SHORT_CIRCUITED(['turn-output'])\n      this.#observabilityEmitter.emit('error', err)\n    }\n\n    emitTurnEnd()\n  }\n}\n"],"mappings":"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"}

package/turn_runner.cjs

@@ -0,0 +1,3 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_turn_runner = require("./turn_runner-CMm2BHdX.js");
+exports.TurnRunner = require_turn_runner.TurnRunner;

package/turn_runner.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The turn runner orchestration surface and its configuration, event, and middleware types.
+ *
+ * @module @nhtio/adk/turn_runner
+ */
+/**
+ * @primaryExport
+ */
+export { TurnRunner } from "./lib/turn_runner";
+/**
+ * @primaryExport
+ */
+export type { TurnRunnerConfig, ResolvedTurnRunnerConfig } from "./lib/contracts/turn_runner_config";
+/**
+ * @primaryExport
+ */
+export type { TurnPipelineMiddlewareFn, TurnStreamableContent, TurnToolCallContent, TurnStartEvent, TurnEndEvent, TurnGateClosedEvent, ToolExecutionStartEvent, ToolExecutionEndEvent, EmitMessageFn, EmitThoughtFn, EmitToolCallFn, EmitToolExecutionStartFn, EmitToolExecutionEndFn, OpenGateFn, TurnEvents, TurnEvent, TurnEventListener, TurnObservabilityEvents, TurnObservabilityEvent, TurnObservabilityEventListener, } from "./lib/types/turn_runner";
+/**
+ * @primaryExport
+ */
+export type { DispatchExecutorFn, DispatchExecutorHelpers, DispatchExecutorLogChannel, DispatchExecutorLogEntry, DispatchExecutorLogLevel, LogEvent, } from "./lib/types/dispatch_runner";

package/turn_runner.mjs

@@ -0,0 +1,2 @@
+import { t as TurnRunner } from "./turn_runner-y7eyEcJH.mjs";
+export { TurnRunner };

package/types.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });

package/types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Type-only export surface for raw shapes, callbacks, events, hooks, and internal contracts.
+ *
+ * @module @nhtio/adk/types
+ *
+ * @remarks
+ * Type-only barrel — re-exports every shape consumers might annotate against: raw constructor
+ * inputs, callback function signatures, event payloads, hook event maps, middleware function
+ * signatures, validator-resolved configuration shapes, and the runtime-internal context/exception
+ * types (`TurnContext`, `DispatchContext`, `BaseException`, `TurnGate`) for which only a
+ * type and a runtime guard (see the `guards` barrel) are exposed.
+ *
+ * No runtime values are re-exported here; importing this barrel produces no JavaScript output
+ * after type-erasure. Use this when you want one place to grab types without dragging in the
+ * corresponding runtime classes.
+ */
+export type { BaseException } from "./lib/classes/base_exception";
+/**
+ * @primaryExport
+ */
+export type { TurnContext } from "./lib/contracts/turn_runner_context";
+/**
+ * @primaryExport
+ */
+export type { DispatchContext } from "./lib/contracts/dispatch_context";
+export type { TurnGate } from "./lib/classes/turn_gate";
+export type { RawIdentity } from "./lib/classes/identity";
+export type { RawMemory } from "./lib/classes/memory";
+export type { RawMessage, MessageRole } from "./lib/classes/message";
+export type { RawThought } from "./lib/classes/thought";
+export type { RawToolCall } from "./lib/classes/tool_call";
+export type { RawTool, ToolHandler } from "./lib/classes/tool";
+export type { RawArtifactTool, ArtifactToolHandler } from "./lib/classes/artifact_tool";
+export type { MergeOptions } from "./lib/classes/tool_registry";
+export type { SpooledArtifactConstructor, ToolMethodDescriptor, } from "./lib/classes/spooled_artifact";
+export type { RawTurnGate } from "./lib/classes/turn_gate";
+export type { SpoolReader } from "./lib/contracts/spool_reader";
+export type { JsonArtifactFormat } from "./lib/classes/spooled_json_artifact";
+export type { MarkdownHeadingEntry, MarkdownCodeEntry, MarkdownSection, } from "./lib/classes/spooled_markdown_artifact";
+export type { TokenEncoding } from "./lib/classes/tokenizable";
+/**
+ * @primaryExport
+ */
+export type { 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, } from "./lib/contracts/turn_runner_context";
+export type { TurnRunnerConfig, ResolvedTurnRunnerConfig } from "./lib/contracts/turn_runner_config";
+export type { TurnPipelineMiddlewareFn, TurnStreamableContent, TurnToolCallContent, TurnStartEvent, TurnEndEvent, TurnGateClosedEvent, ToolExecutionStartEvent, ToolExecutionEndEvent, EmitMessageFn, EmitThoughtFn, EmitToolCallFn, EmitToolExecutionStartFn, EmitToolExecutionEndFn, OpenGateFn, TurnEvents, TurnEvent, TurnEventListener, TurnObservabilityEvents, TurnObservabilityEvent, TurnObservabilityEventListener, } from "./lib/types/turn_runner";
+/**
+ * @primaryExport
+ */
+export type { RawDispatchContext, DispatchMemoryRetrievalFn, DispatchMessageRetrievalFn, DispatchThoughtRetrievalFn, DispatchToolCallRetrievalFn, DispatchToolsRetrievalFn, DispatchStandingInstructionsRefreshFn, DispatchStandingInstructionStoreFn, DispatchStandingInstructionMutateFn, DispatchStandingInstructionDeleteFn, DispatchMemoryStoreFn, DispatchMemoryMutateFn, DispatchMemoryDeleteFn, DispatchMessageStoreFn, DispatchMessageMutateFn, DispatchMessageDeleteFn, DispatchThoughtStoreFn, DispatchThoughtMutateFn, DispatchThoughtDeleteFn, DispatchToolCallStoreFn, DispatchToolCallMutateFn, DispatchToolCallDeleteFn, } from "./lib/contracts/dispatch_context";
+/**
+ * @primaryExport
+ */
+export type { DispatchContextHooks, DispatchContextHookRegistrations, } from "./lib/types/dispatch_context";
+export type { RawDispatchRunnerInput } from "./lib/dispatch_runner";
+export type { DispatchPipelineMiddlewareFn, DispatchExecutorFn, DispatchExecutorHelpers, DispatchExecutorLogChannel, DispatchExecutorLogEntry, DispatchExecutorLogLevel, LogEvent, DispatchStartEvent, DispatchEndEvent, IterationStartEvent, IterationEndEvent, DispatchRunnerFunctionalHooks, DispatchRunnerObservabilityHooks, DispatchRunnerFunctionalHookRegistrations, DispatchRunnerObservabilityHookRegistrations, } from "./lib/types/dispatch_runner";

package/vite-env.d.ts

@@ -0,0 +1,23 @@
+/// <reference types="vite/client" />
+/// <reference types="vite/client" />
+// eslint-disable-next-line @typescript-eslint/naming-convention
+declare const __VERSION__: string;
+// eslint-disable-next-line @typescript-eslint/naming-convention
+declare const __TEST_ENV__: Record<string, string>;
+declare module '*.vue' {
+    import type { DefineComponent } from 'vue';
+    const component: DefineComponent<Record<string, never>, Record<string, never>, unknown>;
+    export default component;
+}
+declare module '@localSearchIndex' {
+    const index: Record<string, () => Promise<{
+        default: string;
+    }>>;
+    export default index;
+}
+// Vite virtual module synthesized by `adkDtsPlugin` (docs/.vitepress/config.mts):
+// a map of @nhtio/adk .d.ts file contents fed to Monaco for in-editor types.
+declare module 'virtual:adk-dts' {
+    const dts: Record<string, string>;
+    export default dts;
+}