AttractorEx.Agent.Session (attractor_phoenix v0.1.0)

Copy Markdown View Source

Stateful coding-agent loop built on top of AttractorEx.LLM.Client.

A session owns request construction, conversation history, tool execution, tool result truncation, steering and follow-up queues, loop detection, subagent lifecycle management, lifecycle events, and layered project-instruction discovery across ancestor AGENTS.md/provider-specific docs with a shared 32 KB prompt budget.

Summary

Types

state()
t()
turn()

Functions

abort(session)

Marks the session as aborted and closed.

close(session)

Closes the session without aborting an in-flight tool.

follow_up(session, message)

Queues a follow-up user input to run after the current submission completes.

new(llm_client, profile, opts \\ [])

Builds a new coding-agent session.

run_subagent_tool(session, tool_name, args)

Executes a session-managed subagent tool and returns {output, updated_session}.

steer(session, message)

Queues steering text to be injected on the next round.

submit(session, user_input)

Submits a user message into the agent loop.

Types

state()

@type state() :: :idle | :processing | :awaiting_input | :closed

t()

@type t() :: %AttractorEx.Agent.Session{
  abort_signaled: boolean(),
  config: AttractorEx.Agent.SessionConfig.t(),
  depth: non_neg_integer(),
  events: [AttractorEx.Agent.Event.t()],
  execution_env: term(),
  followup_queue: :queue.queue(String.t()),
  history: [turn()],
  id: String.t(),
  llm_client: AttractorEx.LLM.Client.t(),
  provider_profile: AttractorEx.Agent.ProviderProfile.t(),
  state: state(),
  steering_queue: :queue.queue(String.t()),
  subagents: map()
}

turn()

@type turn() ::
  %{type: :user, content: String.t(), timestamp: DateTime.t()}
  | %{
      type: :assistant,
      content: String.t(),
      tool_calls: list(),
      reasoning: String.t() | nil,
      usage: map(),
      response_id: String.t() | nil,
      timestamp: DateTime.t()
    }
  | %{
      type: :tool_results,
      results: [AttractorEx.Agent.ToolResult.t()],
      timestamp: DateTime.t()
    }
  | %{type: :steering, content: String.t(), timestamp: DateTime.t()}
  | %{type: :system, content: String.t(), timestamp: DateTime.t()}

Functions

abort(session)

@spec abort(t()) :: t()

Marks the session as aborted and closed.

close(session)

@spec close(t()) :: t()

Closes the session without aborting an in-flight tool.

follow_up(session, message)

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

Queues a follow-up user input to run after the current submission completes.

new(llm_client, profile, opts \\ [])

@spec new(
  AttractorEx.LLM.Client.t(),
  AttractorEx.Agent.ProviderProfile.t(),
  keyword()
) :: t()

Builds a new coding-agent session.

run_subagent_tool(session, tool_name, args)

@spec run_subagent_tool(t(), String.t(), map()) ::
  {String.t() | map() | list() | term(), t()} | no_return()

Executes a session-managed subagent tool and returns {output, updated_session}.

steer(session, message)

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

Queues steering text to be injected on the next round.

submit(session, user_input)

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

Submits a user message into the agent loop.