Agentix.Turn (Agentix v0.1.0)

The per-turn context handed to :server tool callbacks and to hooks.

A turn carries the assembled context sent to the model, the user_message that opened the turn, an opaque turn_ref, and the scope of the caller who is acting this turn. The scope is enforced — a turn always carries one (system scope for timeout/recovery-driven turns).

Two fields serve the hook pipeline: injections accumulates the ContentParts a pre-hook adds (appended at the context tail at assembly time, via Agentix.Hook.inject/2), and assistant_message carries the finalized message to a post-hook (nil for pre-hooks and tool callbacks).

Inside a :server tool callback, report_progress/2 streams incremental progress to the live-event plane (the agent/tool_call_id fields are set by the dispatcher for that call; both are nil for hooks and outside a tool callback).

Built with new/1; rejects unknown keys.

Summary

Types

t()

Functions

new(attrs)

Builds a turn from attrs. Requires a %Agentix.Scope{} under :scope. Raises ArgumentError on unknown keys or a missing/invalid scope.

report_progress(turn, payload)

Reports incremental progress for the in-flight :server tool call this turn is running — broadcasts {:tool_progress, tool_call_id, payload} on the conversation's live-event plane (→ the LiveView projection's in_flight_tools). payload is opaque to the core; the default component renders a binary as the tool's status line. A no-op outside a server tool callback (when agent/tool_call_id are unset).

Types

t()

@type t() :: %Agentix.Turn{
  agent: pid() | nil,
  assistant_message: ReqLLM.Message.t() | nil,
  context: ReqLLM.Context.t() | nil,
  injections: [ReqLLM.Message.ContentPart.t()],
  scope: Agentix.Scope.t(),
  tool_call_id: String.t() | nil,
  turn_ref: term(),
  user_message: ReqLLM.Message.t() | nil
}

Functions

new(attrs)

@spec new(keyword() | map()) :: t()

Builds a turn from attrs. Requires a %Agentix.Scope{} under :scope. Raises ArgumentError on unknown keys or a missing/invalid scope.

report_progress(turn, payload)

@spec report_progress(t(), term()) :: :ok