AgentSessionManager.Core.Run (AgentSessionManager v0.1.1)

Represents a single execution run within a session.

A run represents one complete interaction with the AI agent, including input, output, and any intermediate steps (turns).

Run Lifecycle

Runs follow this state machine:

pending -> running -> completed
                  -> failed
                  -> cancelled
                  -> timeout

Fields

id - Unique run identifier
session_id - Parent session identifier
status - Current run status
input - Input data for the run
output - Output data from the run
error - Error information if the run failed
metadata - Arbitrary metadata
turn_count - Number of turns in this run
token_usage - Token usage statistics
started_at - Run start timestamp
ended_at - Run end timestamp

Usage

# Create a new run
{:ok, run} = Run.new(%{session_id: "session-123"})

# Start the run
{:ok, running} = Run.update_status(run, :running)

# Set output and complete
{:ok, completed} = Run.set_output(running, %{response: "Hello!"})

Summary

Types

status()

t()

Functions

from_map(map)

Reconstructs a run from a map.

increment_turn(run)

Increments the turn count by 1.

new(attrs)

Creates a new run with the given attributes.

set_error(run, error)

Sets the error and marks the run as failed.

set_output(run, output)

Sets the output and marks the run as completed.

to_map(run)

Converts a run to a map suitable for JSON serialization.

update_status(run, status)

Updates the run status.

update_token_usage(run, usage)

Updates token usage statistics.

Types

status()

@type status() :: :pending | :running | :completed | :failed | :cancelled | :timeout

t()

@type t() :: %AgentSessionManager.Core.Run{
  ended_at: DateTime.t() | nil,
  error: map() | nil,
  id: String.t() | nil,
  input: map() | nil,
  metadata: map(),
  output: map() | nil,
  session_id: String.t() | nil,
  started_at: DateTime.t() | nil,
  status: status(),
  token_usage: map(),
  turn_count: non_neg_integer()
}

Functions

from_map(map)

@spec from_map(map()) :: {:ok, t()} | {:error, AgentSessionManager.Core.Error.t()}

Reconstructs a run from a map.

increment_turn(run)

@spec increment_turn(t()) :: {:ok, t()}

Increments the turn count by 1.

new(attrs)

@spec new(map()) :: {:ok, t()} | {:error, AgentSessionManager.Core.Error.t()}

Creates a new run with the given attributes.

Required

:session_id - The parent session identifier

Optional

:id - Custom ID (auto-generated if not provided)
:input - Input data for the run
:metadata - Arbitrary metadata map

Examples

iex> Run.new(%{session_id: "session-123"})
{:ok, %Run{session_id: "session-123", status: :pending, ...}}

iex> Run.new(%{})
{:error, %Error{code: :validation_error, ...}}

set_error(run, error)

@spec set_error(t(), map()) :: {:ok, t()}

Sets the error and marks the run as failed.

set_output(run, output)

@spec set_output(t(), map()) :: {:ok, t()}

Sets the output and marks the run as completed.

to_map(run)

@spec to_map(t()) :: map()

Converts a run to a map suitable for JSON serialization.

update_status(run, status)

@spec update_status(t(), status()) ::
  {:ok, t()} | {:error, AgentSessionManager.Core.Error.t()}

Updates the run status.

Valid statuses

:pending - Run created but not started
:running - Run is currently executing
:completed - Run completed successfully
:failed - Run failed
:cancelled - Run was cancelled
:timeout - Run timed out

Terminal statuses (:completed, :failed, :cancelled, :timeout) will automatically set the ended_at timestamp.

Examples

iex> {:ok, run} = Run.new(%{session_id: "session"})
iex> Run.update_status(run, :running)
{:ok, %Run{status: :running, ended_at: nil, ...}}

iex> Run.update_status(run, :completed)
{:ok, %Run{status: :completed, ended_at: %DateTime{}, ...}}

update_token_usage(run, usage)

@spec update_token_usage(t(), map()) :: {:ok, t()}

Updates token usage statistics.

Token usage is accumulated across multiple updates.