Middleware and outcomes

middleware

middleware(
    *,
    hooks: Iterable[HookPoint | str],
    fail_mode: FailMode,
    band: Band | str = APP,
    timeout: timedelta | str | float | None = None,
    name: str | None = None,
    config: type[BaseModel] | None = None,
    sample: Mapping[str, Any] | None = None,
) -> Callable[[Callable[..., Any]], MiddlewareDef]

Declare a middleware (DESIGNS No. 8).

fail_mode is required (R2, ADR-0014). band is only a default for when the spec doesn't assign one, and it can't be baseline: only the org baseline profile puts middleware there (S8).

Example

@middleware(hooks=["tool.before"], fail_mode="closed", timeout="2s") ... async def no_weekend_refunds(event, env): ... return None

Raises:

Type	Description
ValueError	For an unknown hook or fail mode, the baseline band, or a non-positive timeout.
TypeError	If the target isn't an async function or a class.

MiddlewareDef dataclass

MiddlewareDef(
    name: str,
    target: Callable[..., Any],
    hooks: tuple[HookPoint, ...],
    band: Band,
    fail_mode: FailMode,
    timeout: timedelta | None,
    config: type[BaseModel] | None = None,
    description: str | None = None,
    sample: Mapping[str, Any] | None = None,
)

A declared middleware, as contributed by a plugin.

Attributes:

Name	Type	Description
name	str	The name given to the decorator; a plugin qualifies a bare name with its namespace (acme.no_weekend_refunds).
target	Callable[..., Any]	The decorated async function, or a class whose instances are async callables. A class is built with its config model.
hooks	tuple[HookPoint, ...]	The hook points it attaches to. A spec may narrow them.
band	Band	The band it runs in when the spec doesn't assign one.
fail_mode	FailMode	What a raise or timeout turns into: closed -> Block, open -> Continue plus a trace record.
timeout	timedelta | None	How long one call may take, or None for no limit.
config	type[BaseModel] | None	The settings model for a class middleware.

sample class-attribute instance-attribute

sample: Mapping[str, Any] | None = None

Settings the conformance suite builds a class middleware with (T5).

build

build(settings: Mapping[str, Any] | None = None) -> Handler

Return the callable to install, validating settings against config.

Raises:

Type	Description
SpecError	If the settings are invalid, or given to a middleware that takes none.

Outcomes

Continue

Bases: _Outcome

Proceed. With modified, later middleware and the operation see the new payload.

Block

Bases: _Outcome

Refuse. The step never executes and the run ends blocked.

Suspend

Bases: _Outcome

Pause the run durably until an approver answers.

Escalate

Bases: _Outcome

Stop the automated path and hand the run to a human queue.

Retry

Bases: _Outcome

Redo the step, within the step's retry or repair budget.

Hook points and bands

HookPoint

Bases: StrEnum

A named moment in the run lifecycle. The set is fixed and versioned (R11).

Band

Bases: StrEnum

Middleware priority bands, outermost first.

The spec assigns bands; a plugin can't place itself in baseline (S8).

Direction

Bases: StrEnum

Inbound hooks run outermost-first; outbound hooks run innermost-first.

Hook events

HookEvent module-attribute

HookEvent = Annotated[
    RunStartEvent
    | InputEvent
    | RouteEvent
    | ContextEvent
    | ModelRequestEvent
    | ModelResponseEvent
    | StreamChunkEvent
    | ToolCallEvent
    | ToolResultEvent
    | OutputEvent
    | ApprovalResolvedEvent
    | RunErrorEvent
    | RunEndEvent,
    Field(discriminator="hook"),
]

Any hook event, discriminated by its hook field.

RunStartEvent

Bases: _Event

InputEvent

Bases: _Event

RouteEvent

Bases: _Event

ContextEvent

Bases: _Event

ModelRequestEvent

Bases: _Event

ModelResponseEvent

Bases: _Event

StreamChunkEvent

Bases: _Event

ToolCallEvent

Bases: _Event

ToolResultEvent

Bases: _Event

OutputEvent

Bases: _Event

ApprovalResolvedEvent

Bases: _Event

RunErrorEvent

Bases: _Event

RunEndEvent

Bases: _Event