@nhtio/adk 0.1.0-master-f0aa531d

package/runtime-CrEPIFgr.mjs

@@ -0,0 +1,346 @@
+import { t as createException } from "./exceptions-NrzIHw_R.mjs";
+//#region src/lib/exceptions/runtime.ts
+/**
+* Thrown by {@link @nhtio/adk!TurnRunner} when the supplied config object fails schema validation at
+* construction time.
+*
+* @remarks
+* Marked fatal — a misconfigured runner must not be allowed to execute turns.
+*
+* @group Turn Runner Construction
+*/
+var E_INVALID_TURN_RUNNER_CONFIG = createException("E_INVALID_TURN_RUNNER_CONFIG", "The turn runner cannot be instantiated with the provided configuration.", "E_INVALID_TURN_RUNNER_CONFIG", 529, true);
+/**
+* Thrown by {@link @nhtio/adk!TurnRunner} when the {@link @nhtio/adk!TurnContext} supplied to `run` fails schema
+* validation.
+*
+* @remarks
+* Marked fatal — an invalid context indicates a programming error in the caller, not a
+* recoverable runtime condition. Thrown synchronously out of `run()` before `turnStart` is
+* emitted.
+*
+* @group Turn Input Validation
+*/
+var E_INVALID_TURN_CONTEXT = createException("E_INVALID_TURN_CONTEXT", "The turn runner received an invalid context object.", "E_INVALID_TURN_CONTEXT", 529, true);
+/**
+* Emitted (via the `error` event) when a non-abort error propagates out of the input
+* middleware pipeline during {@link @nhtio/adk!TurnRunner.run}.
+*
+* @remarks
+* Not fatal — the turn runner emits this on the `error` event rather than throwing, so
+* registered listeners can handle or log the failure without crashing the pipeline. Dispatch
+* and output middleware are skipped; `turnEnd` still fires.
+*
+* @group Pipelines
+*/
+var E_INPUT_PIPELINE_ERROR = createException("E_INPUT_PIPELINE_ERROR", "An error occurred in the input pipeline.", "E_INPUT_PIPELINE_ERROR", 500, false);
+/**
+* Emitted (via the `error` event) when a non-abort error propagates out of the output
+* middleware pipeline during {@link @nhtio/adk!TurnRunner.run}.
+*
+* @remarks
+* Not fatal — the turn runner emits this on the `error` event rather than throwing, so
+* registered listeners can handle or log the failure without crashing the pipeline. `turnEnd`
+* still fires.
+*
+* @group Pipelines
+*/
+var E_OUTPUT_PIPELINE_ERROR = createException("E_OUTPUT_PIPELINE_ERROR", "An error occurred in the output pipeline.", "E_OUTPUT_PIPELINE_ERROR", 500, false);
+/**
+* Emitted (via the `error` event) when a middleware pipeline resolves without reaching its
+* terminal handler and without the turn being aborted. Indicates that some middleware
+* returned without calling `next` and without signalling a deliberate refusal via the turn's
+* abort controller.
+*
+* @remarks
+* Not fatal — the runner emits this on the `error` event so the failure is observable, then
+* proceeds to short-circuit the remainder of the turn the same way any other pipeline error
+* would. The constructor takes a single positional argument identifying the pipeline that
+* short-circuited: one of `'turn-input'`, `'turn-output'`, `'dispatch-input'`, or `'dispatch-output'`.
+*
+* Deliberate refusals should call `ctx.abort(reason)`, which sets the `'aborted'` outcome
+* instead of emitting this error.
+*
+* @warning
+* This is a **detection condition**, not a thrown exception. The runner constructs and emits
+* the code itself when it detects a missing `next()` on the unwind — nothing in user code
+* throws it. Upstream post-steps still run normally.
+*
+* @example
+* ```ts
+* throw new E_PIPELINE_SHORT_CIRCUITED(['turn-input'])
+* ```
+*
+* @group Pipelines
+*/
+var E_PIPELINE_SHORT_CIRCUITED = createException("E_PIPELINE_SHORT_CIRCUITED", "The '%s' middleware pipeline short-circuited without calling next or aborting the turn.", "E_PIPELINE_SHORT_CIRCUITED", 500, false);
+/**
+* Thrown when a registry is initialised with a value that is defined but not a plain object.
+*
+* @remarks
+* Registries expect either `undefined` (empty start) or a plain object as their initial value.
+* Passing a primitive, array, class instance, or other non-object signals a programming error
+* in the caller.
+*
+* @group Primitive Validation
+*/
+var E_INVALID_INITIAL_REGISTRY_VALUE = createException("E_INVALID_INITIAL_REGISTRY_VALUE", "Attempted to initialize a registry with a defined non-object value.", "E_INVALID_INITIAL_REGISTRY_VALUE", 500, true);
+/**
+* Thrown when a {@link @nhtio/adk!Memory} is initialised with a value that fails schema validation.
+*
+* @remarks
+* `Memory` requires all fields — `id`, `content`, `confidence`, `importance`, `createdAt`,
+* `updatedAt` — to be present and of the correct type. Passing an incomplete or incorrectly
+* typed object signals a programming error in the caller, not a recoverable runtime condition.
+*
+* @group Primitive Validation
+*/
+var E_INVALID_INITIAL_MEMORY_VALUE = createException("E_INVALID_INITIAL_MEMORY_VALUE", "Attempted to initialize a memory with an invalid value.", "E_INVALID_INITIAL_MEMORY_VALUE", 500, true);
+/**
+* Thrown when a {@link @nhtio/adk!Retrievable} is initialised with a value that fails schema validation.
+*
+* @remarks
+* `Retrievable` requires `id`, `content`, `trustTier`, `createdAt`, and `updatedAt` to be present
+* and of the correct type, and `trustTier` must be one of `'first-party'`, `'third-party-public'`,
+* or `'third-party-private'`. The `trustTier` decision must be made consciously by the retrieval
+* middleware at construction time — there is no default. Passing an incomplete or incorrectly
+* typed object signals a programming error in the caller, not a recoverable runtime condition.
+*
+* @group Primitive Validation
+*/
+var E_INVALID_INITIAL_RETRIEVABLE_VALUE = createException("E_INVALID_INITIAL_RETRIEVABLE_VALUE", "Invalid initial value supplied to Retrievable constructor.", "E_INVALID_INITIAL_RETRIEVABLE_VALUE", 500, true);
+/**
+* Thrown when a {@link @nhtio/adk!Message} is initialised with a value that fails schema validation.
+*
+* @remarks
+* `Message` requires `id`, `role` (`user` or `assistant`), `content`, `createdAt`, and
+* `updatedAt` to be present and of the correct type. Passing an incomplete or incorrectly
+* typed object signals a programming error in the caller, not a recoverable runtime condition.
+*
+* @group Primitive Validation
+*/
+var E_INVALID_INITIAL_MESSAGE_VALUE = createException("E_INVALID_INITIAL_MESSAGE_VALUE", "Attempted to initialize a message with an invalid value.", "E_INVALID_INITIAL_MESSAGE_VALUE", 500, true);
+/**
+* Thrown when an {@link @nhtio/adk!Identity} is initialised with a value that fails schema validation.
+*
+* @remarks
+* `Identity` requires both `identifier` (string or number) and `representation` (string or
+* {@link @nhtio/adk!Tokenizable}) to be present and of the correct type. Passing an incomplete or
+* incorrectly typed object signals a programming error in the caller.
+*
+* @group Primitive Validation
+*/
+var E_INVALID_INITIAL_IDENTITY_VALUE = createException("E_INVALID_INITIAL_IDENTITY_VALUE", "Attempted to initialize an identity with an invalid value.", "E_INVALID_INITIAL_IDENTITY_VALUE", 500, true);
+/**
+* Thrown when a {@link @nhtio/adk!Thought} is initialised with a value that fails schema validation.
+*
+* @remarks
+* `Thought` requires `id`, `content`, `createdAt`, and `updatedAt` to be present and of the
+* correct type. Passing an incomplete or incorrectly typed object signals a programming error
+* in the caller, not a recoverable runtime condition.
+*
+* @group Primitive Validation
+*/
+var E_INVALID_INITIAL_THOUGHT_VALUE = createException("E_INVALID_INITIAL_THOUGHT_VALUE", "Attempted to initialize a thought with an invalid value.", "E_INVALID_INITIAL_THOUGHT_VALUE", 500, true);
+/**
+* Thrown when a {@link @nhtio/adk!TurnGate} is constructed with a value that fails schema validation.
+*
+* @remarks
+* Fatal — bad construction arguments indicate a programming error in the caller.
+*
+* @group Gates
+*/
+var E_INVALID_INITIAL_TURN_GATE_VALUE = createException("E_INVALID_INITIAL_TURN_GATE_VALUE", "Attempted to initialize a turn gate with an invalid value.", "E_INVALID_INITIAL_TURN_GATE_VALUE", 500, true);
+/**
+* Thrown synchronously in the caller's context when {@link @nhtio/adk!TurnGate.resolve} is called with a
+* value that fails the gate's schema.
+*
+* @remarks
+* Fatal — passing the wrong type to `resolve()` is a programming error. The internal promise is
+* NOT settled when this is thrown; the gate remains open.
+*
+* @group Gates
+*/
+var E_INVALID_TURN_GATE_RESOLUTION = createException("E_INVALID_TURN_GATE_RESOLUTION", "The value supplied to TurnGate.resolve() failed schema validation.", "E_INVALID_TURN_GATE_RESOLUTION", 500, true);
+/**
+* Thrown (as a rejection reason) when a {@link @nhtio/adk!TurnGate} times out before being resolved.
+*
+* @remarks
+* Not fatal — a timeout is a recoverable runtime condition; the caller may retry or surface it
+* to the user.
+*
+* @warning
+* A timeout does **not** cancel the external event or clear any remote queue. The gate closes
+* locally, but whatever external system was expected to call `gate.resolve()` may still fire
+* later. Orphaned external state must be handled by the caller.
+*
+* @group Gates
+*/
+var E_TURN_GATE_TIMEOUT = createException("E_TURN_GATE_TIMEOUT", "The turn gate timed out before being resolved.", "E_TURN_GATE_TIMEOUT", 408, false);
+/**
+* Thrown (as a rejection reason) when a {@link @nhtio/adk!TurnGate} is aborted — either because the turn's
+* `AbortSignal` fired or because {@link @nhtio/adk!TurnGate.abort} was called directly.
+*
+* @remarks
+* Not fatal — abort is an intentional cancellation, not an error in the caller.
+*
+* @group Gates
+*/
+var E_TURN_GATE_ABORTED = createException("E_TURN_GATE_ABORTED", "The turn gate was aborted before being resolved.", "E_TURN_GATE_ABORTED", 499, false);
+/**
+* Thrown when a {@link @nhtio/adk!SpooledArtifact} is constructed with a value that does not implement the
+* {@link @nhtio/adk!SpoolReader} interface.
+*
+* @remarks
+* Validated at construction time via {@link @nhtio/adk!implementsSpoolReader}. Passing anything that lacks
+* `line`, `byteLength`, or `lineCount` as callable functions signals a programming error in the
+* caller.
+*
+* @group Artifacts
+*/
+var E_NOT_A_SPOOL_READER = createException("E_NOT_A_SPOOL_READER", "The provided value does not implement the SpoolReader interface.", "E_NOT_A_SPOOL_READER", 500, true);
+/**
+* Thrown when a Media is constructed with a value that does not implement the MediaReader
+* interface.
+*
+* @remarks
+* Validated at construction time. Passing anything that lacks `stream` or `byteLength` as
+* callable functions signals a programming error in the caller.
+*
+* @group Artifacts
+*/
+var E_NOT_A_MEDIA_READER = createException("E_NOT_A_MEDIA_READER", "The provided value does not implement the MediaReader interface.", "E_NOT_A_MEDIA_READER", 500, true);
+/**
+* Thrown when a Media is initialised with a value that fails schema validation.
+*
+* @remarks
+* Fatal — bad construction arguments indicate a programming error in the caller.
+*
+* @group Artifacts
+*/
+var E_INVALID_INITIAL_MEDIA_VALUE = createException("E_INVALID_INITIAL_MEDIA_VALUE", "Attempted to initialize a media with an invalid value.", "E_INVALID_INITIAL_MEDIA_VALUE", 500, true);
+/**
+* Thrown when a {@link @nhtio/adk!ToolCall} is initialised with a value that fails schema validation.
+*
+* @remarks
+* `ToolCall` requires `id`, `tool`, `args`, `checksum`, `isComplete`, `isError`, `createdAt`,
+* and `updatedAt` to be present and of the correct type. Passing an incomplete or incorrectly
+* typed object signals a programming error in the caller, not a recoverable runtime condition.
+*
+* @group Primitive Validation
+*/
+var E_INVALID_INITIAL_TOOL_CALL_VALUE = createException("E_INVALID_INITIAL_TOOL_CALL_VALUE", "Attempted to initialize a tool call with an invalid value.", "E_INVALID_INITIAL_TOOL_CALL_VALUE", 500, true);
+/**
+* Thrown when a {@link @nhtio/adk!Tool} is constructed with a value that fails schema validation.
+*
+* @remarks
+* Fatal — bad construction arguments indicate a programming error in the caller.
+*
+* @group Tools
+*/
+var E_INVALID_INITIAL_TOOL_VALUE = createException("E_INVALID_INITIAL_TOOL_VALUE", "Attempted to initialize a tool with an invalid value.", "E_INVALID_INITIAL_TOOL_VALUE", 500, true);
+/**
+* Thrown synchronously when {@link @nhtio/adk!Tool.validate} is called with arguments that fail the tool's
+* input schema.
+*
+* @remarks
+* Not fatal — an arg validation failure in the tool call loop is a caller mistake that can be
+* surfaced as an error response. The tool handler is NOT called when this is thrown.
+*
+* @group Tools
+*/
+var E_INVALID_TOOL_ARGS = createException("E_INVALID_TOOL_ARGS", "The arguments supplied to the tool failed input schema validation.", "E_INVALID_TOOL_ARGS", 422, false);
+/**
+* Thrown (as a rejection reason) when a {@link @nhtio/adk!Tool}'s handler throws during execution.
+*
+* @remarks
+* Not fatal — a downstream tool failure is a recoverable runtime condition. The tool call loop
+* catches this error specifically to report the failure back to the model rather than crashing
+* the pipeline.
+*
+* @group Tools
+*/
+var E_TOOL_DOWNSTREAM_ERROR = createException("E_TOOL_DOWNSTREAM_ERROR", "The tool handler threw an error during execution.", "E_TOOL_DOWNSTREAM_ERROR", 500, false);
+/**
+* Thrown when {@link @nhtio/adk!ToolRegistry.register} is called for a tool name that is already registered
+* and `overwrite` is not `true`.
+*
+* @remarks
+* Fatal — accidentally overwriting a registered tool indicates a programming error. Pass
+* `overwrite: true` to replace an existing tool intentionally.
+*
+* @group Tools
+*/
+var E_TOOL_ALREADY_REGISTERED = createException("E_TOOL_ALREADY_REGISTERED", "A tool with this name is already registered. Pass overwrite: true to replace it.", "E_TOOL_ALREADY_REGISTERED", 409, true);
+/**
+* Thrown when {@link @nhtio/adk!DispatchContext} is constructed with a value that fails schema validation.
+*
+* @remarks
+* Fatal — bad construction arguments indicate a programming error in the caller.
+*
+* @group Dispatch
+*/
+var E_INVALID_LLM_EXECUTION_CONTEXT = createException("E_INVALID_LLM_EXECUTION_CONTEXT", "The LLM execution context cannot be instantiated with the provided value.", "E_INVALID_LLM_EXECUTION_CONTEXT", 529, true);
+/**
+* Thrown (as a rejection reason) when {@link @nhtio/adk!DispatchContext.waitFor} is called on a
+* standalone context that was constructed without a `waitFor` function.
+*
+* @remarks
+* Not fatal — the caller can catch this and handle the case where gate suspension is not
+* supported for this execution context.
+*
+* @group Dispatch
+*/
+var E_LLM_EXECUTION_GATE_NOT_SUPPORTED = createException("E_LLM_EXECUTION_GATE_NOT_SUPPORTED", "waitFor was called on a standalone DispatchContext with no gate function provided.", "E_LLM_EXECUTION_GATE_NOT_SUPPORTED", 501, false);
+/**
+* Thrown when {@link @nhtio/adk!DispatchContext.ack} or {@link @nhtio/adk!DispatchContext.nack} is called on a
+* context that has already been signalled.
+*
+* @remarks
+* Fatal — signalling twice is a programming error in the caller. The first signal wins; the
+* second call is rejected loudly so callers cannot accidentally race between ack and nack.
+*
+* @danger
+* Signalling is **not** silently idempotent. The first `ack()` or `nack()` wins; the second
+* throws immediately. Guard with `if (!ctx.isSignalled)` when more than one seam may signal.
+*
+* @group Dispatch
+*/
+var E_LLM_EXECUTION_ALREADY_SIGNALLED = createException("E_LLM_EXECUTION_ALREADY_SIGNALLED", "ack() or nack() was called on an DispatchContext that has already been signalled.", "E_LLM_EXECUTION_ALREADY_SIGNALLED", 500, true);
+/**
+* Thrown when {@link @nhtio/adk!DispatchRunner.dispatch} receives an input that fails schema validation.
+*
+* @remarks
+* Fatal — invalid dispatch input indicates a programming error in the caller.
+*
+* @group Dispatch
+*/
+var E_INVALID_LLM_DISPATCH_INPUT = createException("E_INVALID_LLM_DISPATCH_INPUT", "The LLM execution runner received an invalid dispatch input.", "E_INVALID_LLM_DISPATCH_INPUT", 529, true);
+/**
+* Emitted (via the observability `error` hook) and re-thrown when a non-abort error propagates
+* out of the input or output middleware pipeline during {@link @nhtio/adk!DispatchRunner.dispatch}.
+*
+* @remarks
+* Not fatal — pipeline errors are recoverable runtime conditions. `dispatch()` rejects with this
+* exception so callers can handle the failure via try/catch. Both `dispatchInputPipeline` and
+* `dispatchOutputPipeline` share this one code — the runner does not split input vs. output at
+* this layer.
+*
+* @group Pipelines
+*/
+var E_DISPATCH_PIPELINE_ERROR = createException("E_DISPATCH_PIPELINE_ERROR", "An error occurred in an LLM execution pipeline.", "E_DISPATCH_PIPELINE_ERROR", 500, false);
+/**
+* Emitted (via the observability `error` hook) and re-thrown when the user-supplied executor
+* callback throws during {@link @nhtio/adk!DispatchRunner.dispatch}.
+*
+* @remarks
+* Not fatal — executor errors are recoverable runtime conditions. `dispatch()` rejects with this
+* exception so callers can handle the failure via try/catch.
+*
+* @group Dispatch
+*/
+var E_LLM_EXECUTION_EXECUTOR_ERROR = createException("E_LLM_EXECUTION_EXECUTOR_ERROR", "The LLM execution executor callback threw an error.", "E_LLM_EXECUTION_EXECUTOR_ERROR", 500, false);
+//#endregion
+export { E_NOT_A_SPOOL_READER as C, E_TOOL_DOWNSTREAM_ERROR as D, E_TOOL_ALREADY_REGISTERED as E, E_TURN_GATE_ABORTED as O, E_NOT_A_MEDIA_READER as S, E_PIPELINE_SHORT_CIRCUITED as T, E_INVALID_TURN_GATE_RESOLUTION as _, E_INVALID_INITIAL_MEMORY_VALUE as a, E_LLM_EXECUTION_EXECUTOR_ERROR as b, E_INVALID_INITIAL_RETRIEVABLE_VALUE as c, E_INVALID_INITIAL_TOOL_VALUE as d, E_INVALID_INITIAL_TURN_GATE_VALUE as f, E_INVALID_TURN_CONTEXT as g, E_INVALID_TOOL_ARGS as h, E_INVALID_INITIAL_MEDIA_VALUE as i, E_TURN_GATE_TIMEOUT as k, E_INVALID_INITIAL_THOUGHT_VALUE as l, E_INVALID_LLM_EXECUTION_CONTEXT as m, E_INPUT_PIPELINE_ERROR as n, E_INVALID_INITIAL_MESSAGE_VALUE as o, E_INVALID_LLM_DISPATCH_INPUT as p, E_INVALID_INITIAL_IDENTITY_VALUE as r, E_INVALID_INITIAL_REGISTRY_VALUE as s, E_DISPATCH_PIPELINE_ERROR as t, E_INVALID_INITIAL_TOOL_CALL_VALUE as u, E_INVALID_TURN_RUNNER_CONFIG as v, E_OUTPUT_PIPELINE_ERROR as w, E_LLM_EXECUTION_GATE_NOT_SUPPORTED as x, E_LLM_EXECUTION_ALREADY_SIGNALLED as y };
+
+//# sourceMappingURL=runtime-CrEPIFgr.mjs.map

package/runtime-CrEPIFgr.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-CrEPIFgr.mjs","names":[],"sources":["../src/lib/exceptions/runtime.ts"],"sourcesContent":["import { createException } from '../utils/exceptions'\n\n/**\n * Thrown by {@link @nhtio/adk!TurnRunner} when the supplied config object fails schema validation at\n * construction time.\n *\n * @remarks\n * Marked fatal — a misconfigured runner must not be allowed to execute turns.\n *\n * @group Turn Runner Construction\n */\nexport const E_INVALID_TURN_RUNNER_CONFIG = createException(\n  'E_INVALID_TURN_RUNNER_CONFIG',\n  'The turn runner cannot be instantiated with the provided configuration.',\n  'E_INVALID_TURN_RUNNER_CONFIG',\n  529,\n  true\n)\n\n/**\n * Thrown by {@link @nhtio/adk!TurnRunner} when the {@link @nhtio/adk!TurnContext} supplied to `run` fails schema\n * validation.\n *\n * @remarks\n * Marked fatal — an invalid context indicates a programming error in the caller, not a\n * recoverable runtime condition. Thrown synchronously out of `run()` before `turnStart` is\n * emitted.\n *\n * @group Turn Input Validation\n */\nexport const E_INVALID_TURN_CONTEXT = createException(\n  'E_INVALID_TURN_CONTEXT',\n  'The turn runner received an invalid context object.',\n  'E_INVALID_TURN_CONTEXT',\n  529,\n  true\n)\n\n/**\n * Emitted (via the `error` event) when a non-abort error propagates out of the input\n * middleware pipeline during {@link @nhtio/adk!TurnRunner.run}.\n *\n * @remarks\n * Not fatal — the turn runner emits this on the `error` event rather than throwing, so\n * registered listeners can handle or log the failure without crashing the pipeline. Dispatch\n * and output middleware are skipped; `turnEnd` still fires.\n *\n * @group Pipelines\n */\nexport const E_INPUT_PIPELINE_ERROR = createException(\n  'E_INPUT_PIPELINE_ERROR',\n  'An error occurred in the input pipeline.',\n  'E_INPUT_PIPELINE_ERROR',\n  500,\n  false\n)\n\n/**\n * Emitted (via the `error` event) when a non-abort error propagates out of the output\n * middleware pipeline during {@link @nhtio/adk!TurnRunner.run}.\n *\n * @remarks\n * Not fatal — the turn runner emits this on the `error` event rather than throwing, so\n * registered listeners can handle or log the failure without crashing the pipeline. `turnEnd`\n * still fires.\n *\n * @group Pipelines\n */\nexport const E_OUTPUT_PIPELINE_ERROR = createException(\n  'E_OUTPUT_PIPELINE_ERROR',\n  'An error occurred in the output pipeline.',\n  'E_OUTPUT_PIPELINE_ERROR',\n  500,\n  false\n)\n\n/**\n * Emitted (via the `error` event) when a middleware pipeline resolves without reaching its\n * terminal handler and without the turn being aborted. Indicates that some middleware\n * returned without calling `next` and without signalling a deliberate refusal via the turn's\n * abort controller.\n *\n * @remarks\n * Not fatal — the runner emits this on the `error` event so the failure is observable, then\n * proceeds to short-circuit the remainder of the turn the same way any other pipeline error\n * would. The constructor takes a single positional argument identifying the pipeline that\n * short-circuited: one of `'turn-input'`, `'turn-output'`, `'dispatch-input'`, or `'dispatch-output'`.\n *\n * Deliberate refusals should call `ctx.abort(reason)`, which sets the `'aborted'` outcome\n * instead of emitting this error.\n *\n * @warning\n * This is a **detection condition**, not a thrown exception. The runner constructs and emits\n * the code itself when it detects a missing `next()` on the unwind — nothing in user code\n * throws it. Upstream post-steps still run normally.\n *\n * @example\n * ```ts\n * throw new E_PIPELINE_SHORT_CIRCUITED(['turn-input'])\n * ```\n *\n * @group Pipelines\n */\nexport const E_PIPELINE_SHORT_CIRCUITED = createException<[string]>(\n  'E_PIPELINE_SHORT_CIRCUITED',\n  \"The '%s' middleware pipeline short-circuited without calling next or aborting the turn.\",\n  'E_PIPELINE_SHORT_CIRCUITED',\n  500,\n  false\n)\n\n/**\n * Thrown when a registry is initialised with a value that is defined but not a plain object.\n *\n * @remarks\n * Registries expect either `undefined` (empty start) or a plain object as their initial value.\n * Passing a primitive, array, class instance, or other non-object signals a programming error\n * in the caller.\n *\n * @group Primitive Validation\n */\nexport const E_INVALID_INITIAL_REGISTRY_VALUE = createException(\n  'E_INVALID_INITIAL_REGISTRY_VALUE',\n  'Attempted to initialize a registry with a defined non-object value.',\n  'E_INVALID_INITIAL_REGISTRY_VALUE',\n  500,\n  true\n)\n\n/**\n * Thrown when a {@link @nhtio/adk!Memory} is initialised with a value that fails schema validation.\n *\n * @remarks\n * `Memory` requires all fields — `id`, `content`, `confidence`, `importance`, `createdAt`,\n * `updatedAt` — to be present and of the correct type. Passing an incomplete or incorrectly\n * typed object signals a programming error in the caller, not a recoverable runtime condition.\n *\n * @group Primitive Validation\n */\nexport const E_INVALID_INITIAL_MEMORY_VALUE = createException(\n  'E_INVALID_INITIAL_MEMORY_VALUE',\n  'Attempted to initialize a memory with an invalid value.',\n  'E_INVALID_INITIAL_MEMORY_VALUE',\n  500,\n  true\n)\n\n/**\n * Thrown when a {@link @nhtio/adk!Retrievable} is initialised with a value that fails schema validation.\n *\n * @remarks\n * `Retrievable` requires `id`, `content`, `trustTier`, `createdAt`, and `updatedAt` to be present\n * and of the correct type, and `trustTier` must be one of `'first-party'`, `'third-party-public'`,\n * or `'third-party-private'`. The `trustTier` decision must be made consciously by the retrieval\n * middleware at construction time — there is no default. Passing an incomplete or incorrectly\n * typed object signals a programming error in the caller, not a recoverable runtime condition.\n *\n * @group Primitive Validation\n */\nexport const E_INVALID_INITIAL_RETRIEVABLE_VALUE = createException(\n  'E_INVALID_INITIAL_RETRIEVABLE_VALUE',\n  'Invalid initial value supplied to Retrievable constructor.',\n  'E_INVALID_INITIAL_RETRIEVABLE_VALUE',\n  500,\n  true\n)\n\n/**\n * Thrown when a {@link @nhtio/adk!Message} is initialised with a value that fails schema validation.\n *\n * @remarks\n * `Message` requires `id`, `role` (`user` or `assistant`), `content`, `createdAt`, and\n * `updatedAt` to be present and of the correct type. Passing an incomplete or incorrectly\n * typed object signals a programming error in the caller, not a recoverable runtime condition.\n *\n * @group Primitive Validation\n */\nexport const E_INVALID_INITIAL_MESSAGE_VALUE = createException(\n  'E_INVALID_INITIAL_MESSAGE_VALUE',\n  'Attempted to initialize a message with an invalid value.',\n  'E_INVALID_INITIAL_MESSAGE_VALUE',\n  500,\n  true\n)\n\n/**\n * Thrown when an {@link @nhtio/adk!Identity} is initialised with a value that fails schema validation.\n *\n * @remarks\n * `Identity` requires both `identifier` (string or number) and `representation` (string or\n * {@link @nhtio/adk!Tokenizable}) to be present and of the correct type. Passing an incomplete or\n * incorrectly typed object signals a programming error in the caller.\n *\n * @group Primitive Validation\n */\nexport const E_INVALID_INITIAL_IDENTITY_VALUE = createException(\n  'E_INVALID_INITIAL_IDENTITY_VALUE',\n  'Attempted to initialize an identity with an invalid value.',\n  'E_INVALID_INITIAL_IDENTITY_VALUE',\n  500,\n  true\n)\n\n/**\n * Thrown when a {@link @nhtio/adk!Thought} is initialised with a value that fails schema validation.\n *\n * @remarks\n * `Thought` requires `id`, `content`, `createdAt`, and `updatedAt` to be present and of the\n * correct type. Passing an incomplete or incorrectly typed object signals a programming error\n * in the caller, not a recoverable runtime condition.\n *\n * @group Primitive Validation\n */\nexport const E_INVALID_INITIAL_THOUGHT_VALUE = createException(\n  'E_INVALID_INITIAL_THOUGHT_VALUE',\n  'Attempted to initialize a thought with an invalid value.',\n  'E_INVALID_INITIAL_THOUGHT_VALUE',\n  500,\n  true\n)\n\n/**\n * Thrown when a {@link @nhtio/adk!TurnGate} is constructed with a value that fails schema validation.\n *\n * @remarks\n * Fatal — bad construction arguments indicate a programming error in the caller.\n *\n * @group Gates\n */\nexport const E_INVALID_INITIAL_TURN_GATE_VALUE = createException(\n  'E_INVALID_INITIAL_TURN_GATE_VALUE',\n  'Attempted to initialize a turn gate with an invalid value.',\n  'E_INVALID_INITIAL_TURN_GATE_VALUE',\n  500,\n  true\n)\n\n/**\n * Thrown synchronously in the caller's context when {@link @nhtio/adk!TurnGate.resolve} is called with a\n * value that fails the gate's schema.\n *\n * @remarks\n * Fatal — passing the wrong type to `resolve()` is a programming error. The internal promise is\n * NOT settled when this is thrown; the gate remains open.\n *\n * @group Gates\n */\nexport const E_INVALID_TURN_GATE_RESOLUTION = createException(\n  'E_INVALID_TURN_GATE_RESOLUTION',\n  'The value supplied to TurnGate.resolve() failed schema validation.',\n  'E_INVALID_TURN_GATE_RESOLUTION',\n  500,\n  true\n)\n\n/**\n * Thrown (as a rejection reason) when a {@link @nhtio/adk!TurnGate} times out before being resolved.\n *\n * @remarks\n * Not fatal — a timeout is a recoverable runtime condition; the caller may retry or surface it\n * to the user.\n *\n * @warning\n * A timeout does **not** cancel the external event or clear any remote queue. The gate closes\n * locally, but whatever external system was expected to call `gate.resolve()` may still fire\n * later. Orphaned external state must be handled by the caller.\n *\n * @group Gates\n */\nexport const E_TURN_GATE_TIMEOUT = createException(\n  'E_TURN_GATE_TIMEOUT',\n  'The turn gate timed out before being resolved.',\n  'E_TURN_GATE_TIMEOUT',\n  408,\n  false\n)\n\n/**\n * Thrown (as a rejection reason) when a {@link @nhtio/adk!TurnGate} is aborted — either because the turn's\n * `AbortSignal` fired or because {@link @nhtio/adk!TurnGate.abort} was called directly.\n *\n * @remarks\n * Not fatal — abort is an intentional cancellation, not an error in the caller.\n *\n * @group Gates\n */\nexport const E_TURN_GATE_ABORTED = createException(\n  'E_TURN_GATE_ABORTED',\n  'The turn gate was aborted before being resolved.',\n  'E_TURN_GATE_ABORTED',\n  499,\n  false\n)\n\n/**\n * Thrown when a {@link @nhtio/adk!SpooledArtifact} is constructed with a value that does not implement the\n * {@link @nhtio/adk!SpoolReader} interface.\n *\n * @remarks\n * Validated at construction time via {@link @nhtio/adk!implementsSpoolReader}. Passing anything that lacks\n * `line`, `byteLength`, or `lineCount` as callable functions signals a programming error in the\n * caller.\n *\n * @group Artifacts\n */\nexport const E_NOT_A_SPOOL_READER = createException(\n  'E_NOT_A_SPOOL_READER',\n  'The provided value does not implement the SpoolReader interface.',\n  'E_NOT_A_SPOOL_READER',\n  500,\n  true\n)\n\n/**\n * Thrown when a Media is constructed with a value that does not implement the MediaReader\n * interface.\n *\n * @remarks\n * Validated at construction time. Passing anything that lacks `stream` or `byteLength` as\n * callable functions signals a programming error in the caller.\n *\n * @group Artifacts\n */\nexport const E_NOT_A_MEDIA_READER = createException(\n  'E_NOT_A_MEDIA_READER',\n  'The provided value does not implement the MediaReader interface.',\n  'E_NOT_A_MEDIA_READER',\n  500,\n  true\n)\n\n/**\n * Thrown when a Media is initialised with a value that fails schema validation.\n *\n * @remarks\n * Fatal — bad construction arguments indicate a programming error in the caller.\n *\n * @group Artifacts\n */\nexport const E_INVALID_INITIAL_MEDIA_VALUE = createException(\n  'E_INVALID_INITIAL_MEDIA_VALUE',\n  'Attempted to initialize a media with an invalid value.',\n  'E_INVALID_INITIAL_MEDIA_VALUE',\n  500,\n  true\n)\n\n/**\n * Thrown when a {@link @nhtio/adk!ToolCall} is initialised with a value that fails schema validation.\n *\n * @remarks\n * `ToolCall` requires `id`, `tool`, `args`, `checksum`, `isComplete`, `isError`, `createdAt`,\n * and `updatedAt` to be present and of the correct type. Passing an incomplete or incorrectly\n * typed object signals a programming error in the caller, not a recoverable runtime condition.\n *\n * @group Primitive Validation\n */\nexport const E_INVALID_INITIAL_TOOL_CALL_VALUE = createException(\n  'E_INVALID_INITIAL_TOOL_CALL_VALUE',\n  'Attempted to initialize a tool call with an invalid value.',\n  'E_INVALID_INITIAL_TOOL_CALL_VALUE',\n  500,\n  true\n)\n\n/**\n * Thrown when a {@link @nhtio/adk!Tool} is constructed with a value that fails schema validation.\n *\n * @remarks\n * Fatal — bad construction arguments indicate a programming error in the caller.\n *\n * @group Tools\n */\nexport const E_INVALID_INITIAL_TOOL_VALUE = createException(\n  'E_INVALID_INITIAL_TOOL_VALUE',\n  'Attempted to initialize a tool with an invalid value.',\n  'E_INVALID_INITIAL_TOOL_VALUE',\n  500,\n  true\n)\n\n/**\n * Thrown synchronously when {@link @nhtio/adk!Tool.validate} is called with arguments that fail the tool's\n * input schema.\n *\n * @remarks\n * Not fatal — an arg validation failure in the tool call loop is a caller mistake that can be\n * surfaced as an error response. The tool handler is NOT called when this is thrown.\n *\n * @group Tools\n */\nexport const E_INVALID_TOOL_ARGS = createException(\n  'E_INVALID_TOOL_ARGS',\n  'The arguments supplied to the tool failed input schema validation.',\n  'E_INVALID_TOOL_ARGS',\n  422,\n  false\n)\n\n/**\n * Thrown (as a rejection reason) when a {@link @nhtio/adk!Tool}'s handler throws during execution.\n *\n * @remarks\n * Not fatal — a downstream tool failure is a recoverable runtime condition. The tool call loop\n * catches this error specifically to report the failure back to the model rather than crashing\n * the pipeline.\n *\n * @group Tools\n */\nexport const E_TOOL_DOWNSTREAM_ERROR = createException(\n  'E_TOOL_DOWNSTREAM_ERROR',\n  'The tool handler threw an error during execution.',\n  'E_TOOL_DOWNSTREAM_ERROR',\n  500,\n  false\n)\n\n/**\n * Thrown when {@link @nhtio/adk!ToolRegistry.register} is called for a tool name that is already registered\n * and `overwrite` is not `true`.\n *\n * @remarks\n * Fatal — accidentally overwriting a registered tool indicates a programming error. Pass\n * `overwrite: true` to replace an existing tool intentionally.\n *\n * @group Tools\n */\nexport const E_TOOL_ALREADY_REGISTERED = createException(\n  'E_TOOL_ALREADY_REGISTERED',\n  'A tool with this name is already registered. Pass overwrite: true to replace it.',\n  'E_TOOL_ALREADY_REGISTERED',\n  409,\n  true\n)\n\n/**\n * Thrown when {@link @nhtio/adk!DispatchContext} is constructed with a value that fails schema validation.\n *\n * @remarks\n * Fatal — bad construction arguments indicate a programming error in the caller.\n *\n * @group Dispatch\n */\nexport const E_INVALID_LLM_EXECUTION_CONTEXT = createException(\n  'E_INVALID_LLM_EXECUTION_CONTEXT',\n  'The LLM execution context cannot be instantiated with the provided value.',\n  'E_INVALID_LLM_EXECUTION_CONTEXT',\n  529,\n  true\n)\n\n/**\n * Thrown (as a rejection reason) when {@link @nhtio/adk!DispatchContext.waitFor} is called on a\n * standalone context that was constructed without a `waitFor` function.\n *\n * @remarks\n * Not fatal — the caller can catch this and handle the case where gate suspension is not\n * supported for this execution context.\n *\n * @group Dispatch\n */\nexport const E_LLM_EXECUTION_GATE_NOT_SUPPORTED = createException(\n  'E_LLM_EXECUTION_GATE_NOT_SUPPORTED',\n  'waitFor was called on a standalone DispatchContext with no gate function provided.',\n  'E_LLM_EXECUTION_GATE_NOT_SUPPORTED',\n  501,\n  false\n)\n\n/**\n * Thrown when {@link @nhtio/adk!DispatchContext.ack} or {@link @nhtio/adk!DispatchContext.nack} is called on a\n * context that has already been signalled.\n *\n * @remarks\n * Fatal — signalling twice is a programming error in the caller. The first signal wins; the\n * second call is rejected loudly so callers cannot accidentally race between ack and nack.\n *\n * @danger\n * Signalling is **not** silently idempotent. The first `ack()` or `nack()` wins; the second\n * throws immediately. Guard with `if (!ctx.isSignalled)` when more than one seam may signal.\n *\n * @group Dispatch\n */\nexport const E_LLM_EXECUTION_ALREADY_SIGNALLED = createException(\n  'E_LLM_EXECUTION_ALREADY_SIGNALLED',\n  'ack() or nack() was called on an DispatchContext that has already been signalled.',\n  'E_LLM_EXECUTION_ALREADY_SIGNALLED',\n  500,\n  true\n)\n\n/**\n * Thrown when {@link @nhtio/adk!DispatchRunner.dispatch} receives an input that fails schema validation.\n *\n * @remarks\n * Fatal — invalid dispatch input indicates a programming error in the caller.\n *\n * @group Dispatch\n */\nexport const E_INVALID_LLM_DISPATCH_INPUT = createException(\n  'E_INVALID_LLM_DISPATCH_INPUT',\n  'The LLM execution runner received an invalid dispatch input.',\n  'E_INVALID_LLM_DISPATCH_INPUT',\n  529,\n  true\n)\n\n/**\n * Emitted (via the observability `error` hook) and re-thrown when a non-abort error propagates\n * out of the input or output middleware pipeline during {@link @nhtio/adk!DispatchRunner.dispatch}.\n *\n * @remarks\n * Not fatal — pipeline errors are recoverable runtime conditions. `dispatch()` rejects with this\n * exception so callers can handle the failure via try/catch. Both `dispatchInputPipeline` and\n * `dispatchOutputPipeline` share this one code — the runner does not split input vs. output at\n * this layer.\n *\n * @group Pipelines\n */\nexport const E_DISPATCH_PIPELINE_ERROR = createException(\n  'E_DISPATCH_PIPELINE_ERROR',\n  'An error occurred in an LLM execution pipeline.',\n  'E_DISPATCH_PIPELINE_ERROR',\n  500,\n  false\n)\n\n/**\n * Emitted (via the observability `error` hook) and re-thrown when the user-supplied executor\n * callback throws during {@link @nhtio/adk!DispatchRunner.dispatch}.\n *\n * @remarks\n * Not fatal — executor errors are recoverable runtime conditions. `dispatch()` rejects with this\n * exception so callers can handle the failure via try/catch.\n *\n * @group Dispatch\n */\nexport const E_LLM_EXECUTION_EXECUTOR_ERROR = createException(\n  'E_LLM_EXECUTION_EXECUTOR_ERROR',\n  'The LLM execution executor callback threw an error.',\n  'E_LLM_EXECUTION_EXECUTOR_ERROR',\n  500,\n  false\n)\n"],"mappings":";;;;;;;;;;;AAWA,IAAa,+BAA+B,gBAC1C,gCACA,2EACA,gCACA,KACA,IACF;;;;;;;;;;;;AAaA,IAAa,yBAAyB,gBACpC,0BACA,uDACA,0BACA,KACA,IACF;;;;;;;;;;;;AAaA,IAAa,yBAAyB,gBACpC,0BACA,4CACA,0BACA,KACA,KACF;;;;;;;;;;;;AAaA,IAAa,0BAA0B,gBACrC,2BACA,6CACA,2BACA,KACA,KACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,IAAa,6BAA6B,gBACxC,8BACA,2FACA,8BACA,KACA,KACF;;;;;;;;;;;AAYA,IAAa,mCAAmC,gBAC9C,oCACA,uEACA,oCACA,KACA,IACF;;;;;;;;;;;AAYA,IAAa,iCAAiC,gBAC5C,kCACA,2DACA,kCACA,KACA,IACF;;;;;;;;;;;;;AAcA,IAAa,sCAAsC,gBACjD,uCACA,8DACA,uCACA,KACA,IACF;;;;;;;;;;;AAYA,IAAa,kCAAkC,gBAC7C,mCACA,4DACA,mCACA,KACA,IACF;;;;;;;;;;;AAYA,IAAa,mCAAmC,gBAC9C,oCACA,8DACA,oCACA,KACA,IACF;;;;;;;;;;;AAYA,IAAa,kCAAkC,gBAC7C,mCACA,4DACA,mCACA,KACA,IACF;;;;;;;;;AAUA,IAAa,oCAAoC,gBAC/C,qCACA,8DACA,qCACA,KACA,IACF;;;;;;;;;;;AAYA,IAAa,iCAAiC,gBAC5C,kCACA,sEACA,kCACA,KACA,IACF;;;;;;;;;;;;;;;AAgBA,IAAa,sBAAsB,gBACjC,uBACA,kDACA,uBACA,KACA,KACF;;;;;;;;;;AAWA,IAAa,sBAAsB,gBACjC,uBACA,oDACA,uBACA,KACA,KACF;;;;;;;;;;;;AAaA,IAAa,uBAAuB,gBAClC,wBACA,oEACA,wBACA,KACA,IACF;;;;;;;;;;;AAYA,IAAa,uBAAuB,gBAClC,wBACA,oEACA,wBACA,KACA,IACF;;;;;;;;;AAUA,IAAa,gCAAgC,gBAC3C,iCACA,0DACA,iCACA,KACA,IACF;;;;;;;;;;;AAYA,IAAa,oCAAoC,gBAC/C,qCACA,8DACA,qCACA,KACA,IACF;;;;;;;;;AAUA,IAAa,+BAA+B,gBAC1C,gCACA,yDACA,gCACA,KACA,IACF;;;;;;;;;;;AAYA,IAAa,sBAAsB,gBACjC,uBACA,sEACA,uBACA,KACA,KACF;;;;;;;;;;;AAYA,IAAa,0BAA0B,gBACrC,2BACA,qDACA,2BACA,KACA,KACF;;;;;;;;;;;AAYA,IAAa,4BAA4B,gBACvC,6BACA,oFACA,6BACA,KACA,IACF;;;;;;;;;AAUA,IAAa,kCAAkC,gBAC7C,mCACA,6EACA,mCACA,KACA,IACF;;;;;;;;;;;AAYA,IAAa,qCAAqC,gBAChD,sCACA,sFACA,sCACA,KACA,KACF;;;;;;;;;;;;;;;AAgBA,IAAa,oCAAoC,gBAC/C,qCACA,qFACA,qCACA,KACA,IACF;;;;;;;;;AAUA,IAAa,+BAA+B,gBAC1C,gCACA,gEACA,gCACA,KACA,IACF;;;;;;;;;;;;;AAcA,IAAa,4BAA4B,gBACvC,6BACA,mDACA,6BACA,KACA,KACF;;;;;;;;;;;AAYA,IAAa,iCAAiC,gBAC5C,kCACA,uDACA,kCACA,KACA,KACF"}

package/skills/adk-assembly/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: adk-assembly
+description: "Use when assembling, configuring, or reviewing an @nhtio/adk agent: TurnRunner wiring, executorCallback, LLM batteries, 25 storage callbacks, context hydration, tools, retrieval, memory, pipelines, events, RawTurnContext, ack/nack, or batteries vs BYO choices."
+license: MIT
+compatibility: "Requires TypeScript/JavaScript project using @nhtio/adk; examples assume Node 20+ or compatible browser/runtime."
+metadata:
+  package: "@nhtio/adk"
+  version: "0.1.0-master-f0aa531d"
+  author: "Jak Giveon <jak@nht.io>"
+  copyright: "© 2025-present New Horizon Technology LTD"
+---
+
+# ADK Assembly
+
+Use this skill to help users build or review an `@nhtio/adk` assembly: the application-owned wiring around the ADK execution chassis.
+
+## Package Metadata
+
+- Package: `@nhtio/adk`
+- Version: `0.1.0-master-f0aa531d`
+- License: MIT
+- Author: Jak Giveon <jak@nht.io>
+- Copyright: © 2025-present New Horizon Technology LTD
+- Compatibility: Requires TypeScript/JavaScript project using `@nhtio/adk`; examples assume Node 20+ or compatible browser/runtime.
+
+ADK does not ship a hidden default agent. Treat every assembly as explicit wiring of:
+
+1. Storage/context callbacks
+2. An executor callback or LLM battery
+3. Optional tools, retrieval, memory, and pipelines
+4. Functional and observability event listeners
+5. A `RawTurnContext` passed to `runner.run()`
+
+## First Integration Workflow
+
+When the user asks to add ADK to a project or create their first agent, load [First integration workflow](./references/first-integration.md) before proposing files.
+
+Prefer this order:
+
+1. Detect package manager, TypeScript setup, runtime, and existing `@nhtio/adk` dependency.
+2. Choose one executor path: mock executor for no-key local smoke test, OpenAI battery for a real Node/server model, WebLLM battery for browser-local execution, or BYO executor for custom providers.
+3. Scaffold the smallest explicit assembly: `noop-storage.ts`, `hydrate-messages.ts`, and an `agent.ts` or project-local equivalent.
+4. Run or provide the narrowest smoke command that proves a `message` event is observed and `turnEnd` fires.
+5. Upgrade one capability at a time: real persistence, tools, retrieval, memory, iteration guards, then telemetry.
+
+Do not start with retrieval, memory, tools, production persistence, and a real model all at once unless the user explicitly asks for a full integration.
+
+## Assembly Procedure
+
+1. Identify the target runtime: Node, browser, worker, CLI, server, or test harness.
+2. Identify the executor path: first-party LLM battery or custom `DispatchExecutorFn`.
+3. Establish the storage baseline before anything else: all 25 callbacks must exist with correct arity.
+4. Add context hydration in `turnInputPipeline`; ADK does not auto-fetch messages, memories, tool calls, tools, retrievables, or standing instructions.
+5. Register tools intentionally: baseline tools in `tools`, dynamic tools by explicitly calling `ctx.fetchTools()` and registering them.
+6. Put retrieval and memory loading in `turnInputPipeline`; put memory extraction or analytics in `turnOutputPipeline` only when success-only behavior is acceptable.
+7. Add dispatch safeguards such as iteration caps in `dispatchInputPipeline`.
+8. Register functional listeners before `runner.run()` so streamed output is not missed.
+9. Keep observability listeners behavior-free; telemetry must not change agent results.
+10. Validate by typechecking or running the narrowest relevant tests/examples.
+
+## Decision Rules
+
+- Use `OpenAIChatCompletionsAdapter` or `WebLLMChatCompletionsAdapter` when the user wants a ready executor.
+- Write a custom `executorCallback` only when provider protocol, prompt rendering, retry policy, tool loop, or lifecycle behavior must differ from batteries.
+- Use no-op storage callbacks only for prototypes/tests; never omit callbacks.
+- Implement real `Message` and `ToolCall` persistence for conversational or tool-using agents.
+- Use storage batteries only for `SpooledArtifact` bytes; they do not satisfy the 25 callback contract.
+- Use `ctx.stash.get()` and `ctx.stash.set()`; do not treat `ctx.stash` as a plain object.
+- Use public imports from `@nhtio/adk` and documented battery entrypoints; do not deep-import from internal `src` or `lib` paths.
+
+## Required References
+
+Load the focused reference that matches the user's task:
+
+- [First integration workflow](./references/first-integration.md) for adding ADK to a project, scaffolding a first runnable turn, or upgrading from mock executor to a real model.
+- [Assembly contract](./references/assembly-contract.md) for the chassis model, minimal runner shape, and batteries-vs-BYO decisions.
+- [Storage and context](./references/storage-and-context.md) for the 25 callbacks, callback arity, context hydration, memory, and retrieval.
+- [Executors, tools, pipelines, and events](./references/executors-tools-pipelines-events.md) for `ack()`/`nack()`, tool execution, middleware placement, and event buses.
+
+Use the canonical docs when the user needs complete examples, API-adjacent prose, or source-of-truth wording. `https://adk-c04022.gitlab.io` is a build-time placeholder and must be left unchanged in source:
+
+- `https://adk-c04022.gitlab.io/llms.txt` — LLM-friendly documentation index.
+- `https://adk-c04022.gitlab.io/llms-full.txt` — Full LLM-friendly documentation corpus.
+- `https://adk-c04022.gitlab.io/api/index.md` — Generated API documentation index.
+- `https://adk-c04022.gitlab.io/quickstart.md` — No-key three-file first turn with a mock executor.
+- `https://adk-c04022.gitlab.io/assembly/` — Assembly overview.
+- `https://adk-c04022.gitlab.io/assembly/minimal-assembly.md` — Minimal runnable assembly.
+- `https://adk-c04022.gitlab.io/assembly/batteries-llm.md` — LLM batteries.
+- `https://adk-c04022.gitlab.io/assembly/batteries-storage.md` — Storage batteries.
+- `https://adk-c04022.gitlab.io/assembly/batteries-tools.md` — Tool batteries.
+- `https://adk-c04022.gitlab.io/assembly/byo-llm.md` — Custom executor guidance.
+- `https://adk-c04022.gitlab.io/assembly/byo-storage.md` — 25 callback storage contract.
+- `https://adk-c04022.gitlab.io/assembly/byo-tools.md` — Custom tool definitions and registries.
+- `https://adk-c04022.gitlab.io/assembly/byo-retrieval.md` — Retrieval and trust-tier guidance.
+- `https://adk-c04022.gitlab.io/assembly/byo-memory.md` — Memory lifecycle guidance.
+- `https://adk-c04022.gitlab.io/assembly/pipelines.md` — Pipeline placement rules.
+- `https://adk-c04022.gitlab.io/assembly/events.md` — Functional and observability event buses.
+
+## Common Failure Checks
+
+- Missing one of the 25 callbacks or using `async () => []` where ADK requires `(ctx) => []`.
+- Forgetting that every executor invocation must call exactly one terminal signal: `ctx.ack()` on success or `ctx.nack(error)` on failure.
+- Expecting `runner.run()` to return the assistant text; it returns `Promise<void>` and output comes through events.
+- Forgetting `autoAck: true` when directly wiring an LLM battery for a simple one-shot turn.
+- Putting primary model reasoning in middleware or event listeners instead of the executor.
+- Loading no messages because `turnInputPipeline` never calls `ctx.fetchMessages()` and `.add()`s results into `ctx.turnMessages`.
+- Doing turn-scoped work such as history, retrieval, memory, or standing-instruction hydration in dispatch pipelines; dispatch middleware runs once per executor iteration.
+- Treating first-party, public third-party, and private/user-supplied retrievables as equivalent trust sources.
+- Relying on `turnOutputPipeline` for cleanup that must run after failures.

package/skills/adk-assembly/references/assembly-contract.md

@@ -0,0 +1,66 @@
+# Assembly Contract
+
+ADK is an execution chassis, not a pre-assembled agent. The library owns runners, loop mechanics, primitive validation, event buses, and callback contracts. The application owns model execution, persistence, prompt policy, retrieval, memory policy, tools, deployment, and observability.
+
+## Minimum Working Shape
+
+A runnable turn needs:
+
+1. A `TurnRunner` configuration with all required storage/context callbacks.
+2. An `executorCallback` implementing `DispatchExecutorFn`, or a battery executor.
+3. Optional `tools`, `turnInputPipeline`, `turnOutputPipeline`, `dispatchInputPipeline`, and `dispatchOutputPipeline` arrays.
+4. Functional listeners registered before `runner.run()` if output should be streamed.
+5. A `RawTurnContext` with `turnAbortController`, `systemPrompt`, and `standingInstructions`.
+
+`runner.run(rawCtx)` resolves to `Promise<void>`. It does not return assistant output.
+
+## Ownership Boundary
+
+| Area      | ADK owns                                      | Application owns                                        |
+| --------- | --------------------------------------------- | ------------------------------------------------------- |
+| Execution | `TurnRunner`, `DispatchRunner`, dispatch loop | `executorCallback`, model/provider calls, retry policy  |
+| State     | primitive validation, context APIs            | 25 callbacks, database writes, fetch policy             |
+| Logic     | middleware structure, callback invocation     | tools, retrieval, memory lifecycle, business rules      |
+| Context   | typed primitive containers                    | prompt construction, history selection, context budgets |
+| Events    | functional and observability buses            | UI streaming, telemetry sinks, tracing                  |
+
+## Batteries vs. Bring Your Own
+
+Use batteries when the default behavior matches the product:
+
+- `@nhtio/adk/batteries/llm/openai_chat_completions` for OpenAI-compatible Chat Completions endpoints.
+- `@nhtio/adk/batteries/llm/webllm_chat_completions` for browser-local WebLLM execution.
+- `@nhtio/adk/batteries` and category paths for prebuilt tool instances.
+- `@nhtio/adk/batteries/storage/*` only for `SpooledArtifact` byte storage.
+
+Bring your own implementation when you need different provider protocol, custom rendering, custom persistence, custom retrieval, custom memory policy, or product-specific tool behavior.
+
+## Minimal Assembly Checklist
+
+- Import public API from `@nhtio/adk` and documented battery paths.
+- Create or import a 25-callback storage adapter.
+- Seed user messages through `fetchMessagesCallback`, not `RawTurnContext`.
+- Add message hydration middleware to `turnInputPipeline`.
+- Choose an executor and ensure it terminates with `ack()`/`nack()` or battery `autoAck`.
+- Register `runner.on('message', ...)` before `runner.run()`.
+- Pass `standingInstructions: []` explicitly when there are no standing instructions.
+
+## RawTurnContext Rules
+
+`RawTurnContext` contains turn metadata, not conversation history:
+
+- `turnAbortController`: required `AbortController`.
+- `systemPrompt`: required string or tokenizable system behavior.
+- `standingInstructions`: required by TypeScript; pass `[]` if empty.
+- `stash`: optional turn-scoped metadata registry source.
+
+Messages, memories, retrievables, thoughts, tool calls, and dynamic tools are loaded by callbacks that your own middleware or executor explicitly invokes.
+
+## Validation Strategy
+
+Prefer the narrowest validation that exercises the changed assembly:
+
+1. Typecheck the files that import ADK APIs.
+2. Run relevant unit or smoke tests if present.
+3. For examples/docs, run only the relevant example unless the user asks for broader validation.
+4. Do not run docs builds while a VitePress docs dev server is active unless the user explicitly approves.