LemonRouter (lemon_router v0.1.0)

LemonRouter provides orchestration and routing for agent runs.

This app is responsible for:

Session key management and parsing
Run orchestration and lifecycle
Stream coalescing for efficient channel output
Policy merging for tool execution
Abort handling and run cancellation
Bridging between channels and gateway

Session Keys

Session keys provide a stable identifier for routing and state:

Main: agent:<agent_id>:main
Channel: agent:<agent_id>:<channel_id>:<account_id>:<peer_kind>:<peer_id>[:thread:<thread_id>]

Architecture

[Channels] -> [Router] -> [Gateway] -> [Engine]
     ^          |
     |          v
     +--- [StreamCoalescer]

Summary

Types

active_run()

A run currently being orchestrated.

run_counts()

Run counts as reported by the orchestrator.

Functions

abort(session_key, reason \\ :user_requested)

Abort a session's active run.

abort_run(run_id, reason \\ :user_requested)

Abort a specific run by ID.

active_run_count()

How many run processes are currently supervised.

active_runs()

Every run currently active, newest first is not guaranteed — callers that care about ordering should sort on :started_at_ms.

available?()

Whether the router runtime is up and able to accept work.

counts()

Orchestrator run counts.

delete_agent_endpoint(agent_id, name)

Delete an endpoint alias.

keep_run_alive(run_id, decision \\ :continue)

Apply a watchdog keepalive decision to a specific run.

list_agent_directory(opts \\ [])

List agent directory entries with routing/session discoverability metadata.

list_agent_endpoints(opts \\ [])

List persisted endpoint aliases.

list_agent_sessions(opts \\ [])

List known sessions from the agent directory/phonebook.

list_agent_targets(opts \\ [])

List known channel targets (for example Telegram rooms/topics) with friendly labels.

resolve_agent_session(agent_id, selector \\ :latest, opts \\ [])

Resolve an agent session selector (:latest, :new, explicit key) to a concrete session.

run_active?(run_id)

Whether run_id is currently active.

send_to_agent(agent_id, prompt, opts \\ [])

Send a message to an agent inbox.

set_agent_endpoint(agent_id, name, target, opts \\ [])

Upsert an endpoint alias for an agent.

submit(params)

Submit a run request to the router.

Types

active_run()

@type active_run() :: %{
  run_id: binary(),
  session_key: binary() | nil,
  agent_id: binary() | nil,
  engine: binary() | nil,
  started_at_ms: integer() | nil
}

A run currently being orchestrated.

run_counts()

@type run_counts() :: %{
  active: non_neg_integer(),
  queued: non_neg_integer(),
  completed_today: non_neg_integer()
}

Run counts as reported by the orchestrator.

Functions

abort(session_key, reason \\ :user_requested)

Abort a session's active run.

abort_run(run_id, reason \\ :user_requested)

Abort a specific run by ID.

active_run_count()

@spec active_run_count() :: non_neg_integer()

How many run processes are currently supervised.

Cheaper than active_runs/0 when only the count is needed; 0 when the router is not running.

active_runs()

@spec active_runs() :: [active_run()]

Every run currently active, newest first is not guaranteed — callers that care about ordering should sort on :started_at_ms.

Returns [] when the router is not running.

available?()

@spec available?() :: boolean()

Whether the router runtime is up and able to accept work.

Use this instead of probing for a router process by name.

counts()

@spec counts() :: run_counts()

Orchestrator run counts.

Always returns the full shape: when the router is not running, every counter is zero rather than the key being absent, so callers can read the fields without guarding.

delete_agent_endpoint(agent_id, name)

@spec delete_agent_endpoint(binary(), binary()) :: :ok | {:error, term()}

Delete an endpoint alias.

keep_run_alive(run_id, decision \\ :continue)

Apply a watchdog keepalive decision to a specific run.

list_agent_directory(opts \\ [])

@spec list_agent_directory(keyword()) :: [map()]

List agent directory entries with routing/session discoverability metadata.

list_agent_endpoints(opts \\ [])

@spec list_agent_endpoints(keyword()) :: [map()]

List persisted endpoint aliases.

list_agent_sessions(opts \\ [])

@spec list_agent_sessions(keyword()) :: [map()]

List known sessions from the agent directory/phonebook.

list_agent_targets(opts \\ [])

@spec list_agent_targets(keyword()) :: [map()]

List known channel targets (for example Telegram rooms/topics) with friendly labels.

resolve_agent_session(agent_id, selector \\ :latest, opts \\ [])

@spec resolve_agent_session(binary(), term(), keyword()) ::
  {:ok, map()} | {:error, term()}

Resolve an agent session selector (:latest, :new, explicit key) to a concrete session.

run_active?(run_id)

@spec run_active?(binary()) :: boolean()

Whether run_id is currently active.

send_to_agent(agent_id, prompt, opts \\ [])

@spec send_to_agent(binary(), binary(), keyword()) ::
  {:ok, %{run_id: binary(), session_key: binary(), selector: term()}}
  | {:error, term()}

Send a message to an agent inbox.

Supports session: :latest | :new | <session_key>.

set_agent_endpoint(agent_id, name, target, opts \\ [])

@spec set_agent_endpoint(binary(), binary(), term(), keyword()) ::
  {:ok, map()} | {:error, term()}

Upsert an endpoint alias for an agent.

submit(params)

@spec submit(LemonCore.RunRequest.t() | map() | keyword()) ::
  {:ok, binary()} | {:error, term()}

Submit a run request to the router.

Accepts either a normalized %LemonCore.RunRequest{} or a legacy map/keyword payload that can be normalized into one.