Planck.Agent.Turn (Planck.Agent v0.3.0)

Turn state for a running agent.

Holds the streaming status, in-flight stream task, and the dissolved fields from TurnState (index, checkpoints), StreamBuffer (text, thinking, calls), and ToolRunner (running, results, loop_counts).

Summary

Types

status()

Status of the turn

t()

Turn information.

Functions

append_call(turn, call)

Add a completed tool call to the stream buffer.

append_text(turn, text)

Append a text delta to the stream buffer.

append_thinking(turn, text)

Append a thinking delta to the stream buffer.

cancel_all_tools(turn)

Kill all in-flight tool task processes.

cancel_stream(turn)

Cancel the in-flight stream task, if any.

continue_turn(turn, pid, reference)

Updates turn to continuation.

mark_tool_done(turn, call_id, result)

Mark a tool call as done. Returns {:ok, updated_turn} or :not_running.

new()

Return a fresh turn state.

prepare_call(turn, tools, agent_id, tool_call)

Resolve, wrap, and track a tool call. Returns {updated_turn, wrapped_fn}.

push_checkpoint(turn, messages)

Push a checkpoint (current message-list length) onto the stack.

rebuild_checkpoints(turn, messages)

Rebuild checkpoints from a message list, preserving the current index.

register_call(turn, tool_call, pid)

Registers tool call.

reset_streaming(turn)

Reset the stream buffer and tool runner to their initial state.

start_turn(turn, pid, reference, messages)

Updates turn to start.

tool_done?(turn)

Return true when all tool calls have completed.

Types

status()

@type status() :: :idle | :streaming | :executing_tools

Status of the turn

t()

@type t() :: %Planck.Agent.Turn{
  buffer_calls: [map()],
  buffer_text: String.t(),
  buffer_thinking: String.t(),
  checkpoints: [non_neg_integer()],
  index: non_neg_integer(),
  loop_counts: %{optional({String.t(), non_neg_integer()}) => non_neg_integer()},
  results: list(),
  running: %{required(String.t()) => %{name: String.t(), pid: pid()}},
  status: status(),
  stream_ref: reference() | nil,
  stream_start: non_neg_integer(),
  stream_task: pid() | nil
}

Turn information.

Functions

append_call(turn, call)

@spec append_call(t(), map()) :: t()

Add a completed tool call to the stream buffer.

append_text(turn, text)

@spec append_text(t(), String.t()) :: t()

Append a text delta to the stream buffer.

append_thinking(turn, text)

@spec append_thinking(t(), String.t()) :: t()

Append a thinking delta to the stream buffer.

cancel_all_tools(turn)

@spec cancel_all_tools(t()) :: :ok

Kill all in-flight tool task processes.

cancel_stream(turn)

@spec cancel_stream(t()) :: :ok

Cancel the in-flight stream task, if any.

continue_turn(turn, pid, reference)

@spec continue_turn(t(), pid(), reference()) :: t()

Updates turn to continuation.

mark_tool_done(turn, call_id, result)

@spec mark_tool_done(t(), String.t(), term()) :: {:ok, t()} | :not_running

Mark a tool call as done. Returns {:ok, updated_turn} or :not_running.

new()

@spec new() :: t()

Return a fresh turn state.

prepare_call(turn, tools, agent_id, tool_call)

@spec prepare_call(t(), tools, agent_id, tool_call) :: {t(), (-> result)}
when tools: %{required(tool_name) => Planck.Agent.Tool.t()},
     agent_id: String.t(),
     tool_call: %{id: String.t(), name: tool_name, args: map()},
     tool_name: String.t(),
     result:
       {:ok, String.t()}
       | {:ok, String.t(), %{ui: Planck.Agent.Tool.ui_content()}}
       | {:error, term()}

Resolve, wrap, and track a tool call. Returns {updated_turn, wrapped_fn}.

push_checkpoint(turn, messages)

@spec push_checkpoint(t(), [Planck.Agent.Message.t()]) :: t()

Push a checkpoint (current message-list length) onto the stack.

rebuild_checkpoints(turn, messages)

@spec rebuild_checkpoints(t(), [Planck.Agent.Message.t()]) :: t()

Rebuild checkpoints from a message list, preserving the current index.

register_call(turn, tool_call, pid)

@spec register_call(t(), tool_call, pid()) :: t()
when tool_call: %{id: String.t(), name: String.t(), args: map()}

Registers tool call.

reset_streaming(turn)

@spec reset_streaming(t()) :: t()

Reset the stream buffer and tool runner to their initial state.

start_turn(turn, pid, reference, messages)

@spec start_turn(t(), pid(), reference(), [Planck.Agent.Message.t()]) :: t()

Updates turn to start.

tool_done?(turn)

@spec tool_done?(t()) :: boolean()

Return true when all tool calls have completed.