BeamAgent.Routing (beam_agent_ex v0.1.0)

Copy Markdown View Source

Elixir facade for canonical BeamAgent backend routing.

This module chooses a backend according to reusable routing policy instead of forcing callers to hard-code backend choice on every session start.

Supported policies are :explicit, :sticky, :round_robin, :failover, :capability_first, and :preferred_then_fallback. Sticky affinity and round-robin cursors are stored as canonical BeamAgent state, but the module itself stays process-free.

The module also acts as the primary session router — starting, stopping, querying, and managing unified sessions after resolving the backend via routing policy.

Summary

Types

fallback_policy()

Fallback behavior after preferred candidates are exhausted.

health_status()

Backend health override for routing.

route_decision()

Routing decision map.

route_policy()

Routing policy name.

route_request()

Routing request map.

Functions

abort(session)

Abort active work on the session.

account_info(session)

Get account info from session init data.

adapter_module(session)

Resolve the adapter facade module for a live session.

backend(session)

Resolve the backend for a live session.

child_spec(opts)

Return a child spec for a unified session after resolving backend routing.

clear()

Clear sticky affinity and round-robin routing state.

delete_session(session_id)

Delete a tracked session from the shared store.

ensure_tables()

Ensure routing state tables exist. Idempotent.

fork_session(session, opts)

Fork a live session.

get_session(session_id)

Read shared session metadata by session id.

get_session_messages(session_id)

Get all visible messages for a session id.

get_session_messages(session_id, opts)

Get visible messages for a session id with options.

health(session)

Return the health state for a live session.

interrupt(session)

Interrupt active work on the session.

list_sessions()

List all tracked sessions in the shared store.

list_sessions(opts)

List tracked sessions with filters.

query(session, prompt)

Send a blocking query with default params.

query(session, prompt, params)

Send a blocking query through the canonical router.

receive_message(session, ref, timeout)

Pull the next message from a live query.

revert_session(session, selector)

Revert a live session.

select_backend(route_request)

Select a backend using a normalized routing request.

select_backend(session_or_opts, route_request)

Select a backend after deriving defaults from a session identity or session opts.

send_control(session, method, params)

Send a control message through the appropriate native or shared path.

send_query(session, prompt, params, timeout)

Send a query and return the live query reference.

server_health(session)

Return high-level server health details when a backend exposes them.

session_info(session)

Query session info for a live session.

set_model(session, model)

Change the model at runtime.

set_permission_mode(session, mode)

Change the permission mode at runtime.

share_session(session)

Share a live session with default opts.

share_session(session, opts)

Share a live session.

start_session(opts)

Start a unified session after resolving explicit or policy-based backend routing.

stop(session)

Stop a live unified session.

summarize_session(session)

Summarize a live session with default opts.

summarize_session(session, opts)

Summarize a live session.

supported_agents(session)

List agents from session init data.

supported_commands(session)

List slash commands from session init data.

supported_models(session)

List models from session init data.

thread_archive(session, thread_id)

Archive a thread.

thread_fork(session, thread_id)

Fork a thread with default opts.

thread_fork(session, thread_id, opts)

Fork a thread.

thread_list(session)

List threads for a live session.

thread_read(session, thread_id)

Read a thread with default opts.

thread_read(session, thread_id, opts)

Read a thread.

thread_resume(session, thread_id)

Resume a thread.

thread_rollback(session, thread_id, selector)

Rollback a thread.

thread_start(session, opts)

Start a thread for a live session.

thread_unarchive(session, thread_id)

Unarchive a thread.

unrevert_session(session)

Clear a session revert state.

unshare_session(session)

Revoke sharing for a live session.

Types

fallback_policy()

@type fallback_policy() :: :beam_agent_routing.fallback_policy()

Fallback behavior after preferred candidates are exhausted.

Supported values are :none and :available.

health_status()

@type health_status() :: :beam_agent_routing.health_status()

Backend health override for routing.

Supported values are :healthy, :degraded, :unhealthy, and :down.

route_decision()

@type route_decision() :: :beam_agent_routing.route_decision()

Routing decision map.

route_policy()

@type route_policy() :: :beam_agent_routing.route_policy()

Routing policy name.

Supported values are :explicit, :sticky, :round_robin, :failover, :capability_first, and :preferred_then_fallback.

route_request()

@type route_request() :: :beam_agent_routing.route_request()

Routing request map.

Functions

abort(session)

@spec abort(pid()) :: :ok | {:error, any()}

Abort active work on the session.

account_info(session)

@spec account_info(pid()) :: {:ok, map()} | {:error, any()}

Get account info from session init data.

adapter_module(session)

@spec adapter_module(pid()) ::
  {:ok, module()} | {:error, :beam_agent_backend.backend_lookup_error()}

Resolve the adapter facade module for a live session.

backend(session)

@spec backend(pid()) ::
  {:ok, :beam_agent_backend.backend()}
  | {:error, :beam_agent_backend.backend_lookup_error()}

Resolve the backend for a live session.

child_spec(opts)

@spec child_spec(:beam_agent_core.session_opts()) :: :supervisor.child_spec()

Return a child spec for a unified session after resolving backend routing.

clear()

@spec clear() :: :ok

Clear sticky affinity and round-robin routing state.

delete_session(session_id)

@spec delete_session(binary()) :: :ok

Delete a tracked session from the shared store.

ensure_tables()

@spec ensure_tables() :: :ok

Ensure routing state tables exist. Idempotent.

fork_session(session, opts)

@spec fork_session(pid(), map()) :: {:ok, map()} | {:error, any()}

Fork a live session.

get_session(session_id)

@spec get_session(binary()) ::
  {:ok, BeamAgent.SessionStore.session_meta()} | {:error, :not_found}

Read shared session metadata by session id.

get_session_messages(session_id)

@spec get_session_messages(binary()) ::
  {:ok, [:beam_agent.message()]} | {:error, :not_found}

Get all visible messages for a session id.

get_session_messages(session_id, opts)

@spec get_session_messages(binary(), BeamAgent.SessionStore.message_opts()) ::
  {:ok, [:beam_agent.message()]} | {:error, :not_found}

Get visible messages for a session id with options.

health(session)

@spec health(pid()) :: atom()

Return the health state for a live session.

interrupt(session)

@spec interrupt(pid()) :: :ok | {:error, any()}

Interrupt active work on the session.

list_sessions()

@spec list_sessions() :: {:ok, [BeamAgent.SessionStore.session_meta()]}

List all tracked sessions in the shared store.

list_sessions(opts)

@spec list_sessions(BeamAgent.SessionStore.list_opts()) ::
  {:ok, [BeamAgent.SessionStore.session_meta()]}

List tracked sessions with filters.

query(session, prompt)

@spec query(pid(), binary()) :: {:ok, [:beam_agent.message()]} | {:error, any()}

Send a blocking query with default params.

query(session, prompt, params)

@spec query(pid(), binary(), map()) ::
  {:ok, [:beam_agent.message()]} | {:error, any()}

Send a blocking query through the canonical router.

receive_message(session, ref, timeout)

@spec receive_message(pid(), reference(), timeout()) ::
  {:ok, :beam_agent.message()} | {:error, any()}

Pull the next message from a live query.

revert_session(session, selector)

@spec revert_session(pid(), map()) :: {:ok, map()} | {:error, any()}

Revert a live session.

select_backend(route_request)

@spec select_backend(route_request()) :: {:ok, route_decision()} | {:error, any()}

Select a backend using a normalized routing request.

select_backend(session_or_opts, route_request)

@spec select_backend(pid() | binary() | map(), route_request()) ::
  {:ok, route_decision()} | {:error, any()}

Select a backend after deriving defaults from a session identity or session opts.

send_control(session, method, params)

@spec send_control(pid(), binary(), map()) :: {:ok, map()} | {:error, any()}

Send a control message through the appropriate native or shared path.

send_query(session, prompt, params, timeout)

@spec send_query(pid(), binary(), :beam_agent_core.query_opts(), timeout()) ::
  {:ok, reference()} | {:error, any()}

Send a query and return the live query reference.

server_health(session)

@spec server_health(pid()) :: {:ok, map()} | {:error, any()}

Return high-level server health details when a backend exposes them.

session_info(session)

@spec session_info(pid()) :: {:ok, map()} | {:error, any()}

Query session info for a live session.

set_model(session, model)

@spec set_model(pid(), binary()) :: {:ok, binary()} | {:error, any()}

Change the model at runtime.

set_permission_mode(session, mode)

@spec set_permission_mode(pid(), binary()) ::
  {:ok, binary() | map()} | {:error, any()}

Change the permission mode at runtime.

share_session(session)

@spec share_session(pid()) :: {:ok, map()} | {:error, any()}

Share a live session with default opts.

share_session(session, opts)

@spec share_session(pid(), map()) :: {:ok, map()} | {:error, any()}

Share a live session.

start_session(opts)

@spec start_session(:beam_agent_core.session_opts()) :: {:ok, pid()} | {:error, any()}

Start a unified session after resolving explicit or policy-based backend routing.

stop(session)

@spec stop(pid()) :: :ok

Stop a live unified session.

summarize_session(session)

@spec summarize_session(pid()) :: {:ok, map()} | {:error, any()}

Summarize a live session with default opts.

summarize_session(session, opts)

@spec summarize_session(pid(), map()) :: {:ok, map()} | {:error, any()}

Summarize a live session.

supported_agents(session)

@spec supported_agents(pid()) :: {:ok, list()} | {:error, any()}

List agents from session init data.

supported_commands(session)

@spec supported_commands(pid()) :: {:ok, list()} | {:error, any()}

List slash commands from session init data.

supported_models(session)

@spec supported_models(pid()) :: {:ok, list()} | {:error, any()}

List models from session init data.

thread_archive(session, thread_id)

@spec thread_archive(pid(), binary()) :: {:ok, map()} | {:error, any()}

Archive a thread.

thread_fork(session, thread_id)

@spec thread_fork(pid(), binary()) :: {:ok, map()} | {:error, any()}

Fork a thread with default opts.

thread_fork(session, thread_id, opts)

@spec thread_fork(pid(), binary(), map()) :: {:ok, map()} | {:error, any()}

Fork a thread.

thread_list(session)

@spec thread_list(pid()) :: {:ok, [map()]} | {:error, any()}

List threads for a live session.

thread_read(session, thread_id)

@spec thread_read(pid(), binary()) :: {:ok, map()} | {:error, any()}

Read a thread with default opts.

thread_read(session, thread_id, opts)

@spec thread_read(pid(), binary(), map()) :: {:ok, map()} | {:error, any()}

Read a thread.

thread_resume(session, thread_id)

@spec thread_resume(pid(), binary()) :: {:ok, map()} | {:error, any()}

Resume a thread.

thread_rollback(session, thread_id, selector)

@spec thread_rollback(pid(), binary(), map()) :: {:ok, map()} | {:error, any()}

Rollback a thread.

thread_start(session, opts)

@spec thread_start(pid(), map()) :: {:ok, map()} | {:error, any()}

Start a thread for a live session.

thread_unarchive(session, thread_id)

@spec thread_unarchive(pid(), binary()) :: {:ok, map()} | {:error, any()}

Unarchive a thread.

unrevert_session(session)

@spec unrevert_session(pid()) :: {:ok, map()} | {:error, any()}

Clear a session revert state.

unshare_session(session)

@spec unshare_session(pid()) :: :ok | {:error, any()}

Revoke sharing for a live session.