Spectre.Turn.Handler behaviour (Spectre v0.3.0)

Copy Markdown View Source

Optional boundary through which another runtime may own a normal turn before Spectre routes it.

Handlers form an ordered pipeline. Each handler returns :cont when Spectre should consult the next handler and eventually its normal router, or {:reply, reply} when that integration owns the current request. A handler cannot inject Spectre state, routes, effects, or awaitables; it can only provide a typed Spectre.Turn.Handler.Reply.

This is a chain-of-responsibility extension, not Spectre's universal turn protocol. Spectre.turn/3 and Spectre.Turn.decision() are the canonical local host contract. A Directive mission, FSM, GenServer, or other stateful runtime should implement this behaviour only when it temporarily owns the user dialogue. Specialized integrations should still prefer Spectre's narrower memory, action, prompt, input, Skill, and telemetry/journal ports.

Distributed protocol concerns such as sender and recipient addresses, correlation, task identity, retries, and delivery guarantees deliberately do not live here.

Summary

Callbacks

Inspects one loaded request and either continues or owns the turn.

Types

response()

@type response() ::
  :cont | {:reply, Spectre.Turn.Handler.Reply.t()} | {:error, term()}

Callbacks

handle_turn(t, keyword)

@callback handle_turn(
  Spectre.Turn.Handler.Request.t(),
  keyword()
) :: response()

Inspects one loaded request and either continues or owns the turn.