Middleware
Capability declarations, step middleware, state, and model-configuration mutation APIs.
CapabilityDeclaration
Access: @nylorun/harness → CapabilityDeclaration, CapabilityItems, CapabilityState
Declares one named contribution to an agent's model surface and step behavior.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Stable capability and middleware id. |
tools | CapabilityItems<ToolDefinition> | No | Tool list, or named slot plus tool list, visible to the model. |
instructions | CapabilityItems<string> | No | Instruction list, or named slot plus instruction list. |
model | ModelDirective | No | Model selection contributed by the capability. |
state | CapabilityState<State> | No | Creates optional state once per session. |
middleware | StepMiddleware<State> | No | Step handler run around the model call. |
CapabilityItems<Item> accepts either readonly Item[] or a value with slot and items.
CapabilityState.create(session, signal) creates the state; its optional dispose(value) cleans it
up when the session ends.
StepMiddleware
Access: @nylorun/harness → StepMiddleware, StepRequest, StepInput
| Parameter | Type | Required | Description |
|---|---|---|---|
request | StepRequest<State> | Yes | Step identity, session identity, arrivals, tool results, transcript, state, and mutation APIs. |
next | () => Promise<StepResponse> | Yes | Continues the middleware chain and model step. Call at most once. |
| Returns | Promise<StepResponse> | — | Response that may be inspected or changed after next(). |
StepInput exposes sessionId, turnId, stepId, turn/step numbers, session identity, arrivals,
tool results, and transcript. A stateful declaration adds state: Promise<State> to the request.
Request mutation APIs
Access: @nylorun/harness → ContextMutationOptions,
ModelConfigurationMutationOptions, ModelDirective
| API | Parameters | Returns | Description |
|---|---|---|---|
request.context.set | slot, items, optional context mutation options | void | Replaces runtime context for one named slot. |
request.configuration.instructions.set | slot, items, optional configuration mutation options | void | Replaces model instructions for one named slot. |
request.configuration.tools.set | slot, tools, optional configuration mutation options | void | Replaces model-visible tools for one named slot. |
request.configuration.model.select | directive, optional reason | void | Selects a model when one has not already won selection. |
request.configuration.model.replace | directive, optional reason | void | Replaces the selected model. |
request.configuration.model.clear | optional reason | void | Removes the selected model. |
Context and configuration mutation options accept optional order and reason. Model selection
uses an optional reason only. Harness records contributors and digests in
ContextSnapshot and ModelConfigurationSnapshot.
StepResponse
Access: @nylorun/harness → StepResponse, Tripwire
| Method | Parameters | Returns | Description |
|---|---|---|---|
candidate() | None | Readonly<ModelCandidate> or undefined | Returns the current candidate, if any. |
toolCalls() | None | readonly ModelToolCall[] | Returns tool calls currently eligible for review. |
replace(candidate) | ModelCandidate | void | Replaces the candidate before tool planning. |
deny(callId, reason) | string, string | void | Converts one tool call into a denied result. |
requireInteraction(callId, interaction) | string, Interaction | void | Requires approval or a response before a tool runs. |
tripwire(error) | Tripwire | StepResponse | Stops the step or session according to the tripwire scope. |
Attempting to call next() twice or mutate a request after its middleware has returned raises a
machine-readable HarnessError.