rho

An agent core for Elixir apps, on a computer or on a phone: the turn loop, sessions, context compaction, tools, and model sign-in, on req_llm.

• Loop (Rho.Loop): a GenServer per session with pi-agent-core's lifecycle: streamed replies, the reply's tool calls in parallel with results in call order, steering and follow-ups while it runs, stop, retries with backoff, rate limits waited out within a budget then a fallback model, a per-day cost cap, a wrap-up turn at the iteration limit, and a reminder when the session's todo list still has open items.
• Sessions (Rho.Session): omp/pi's JSONL session format (version 3), so a session moves between omp on a computer and a rho app on a phone.
• Compaction (Rho.Compaction): pi's local summary method, before a call that would overflow the window and after a provider rejects one.
• Tools (Rho.Tool, Rho.ToolRunner, Rho.ToolRegistry): plain modules; each call in its own task with a timeout and a gate, oversized output spilled to an artifact the agent pages through.
• Models (Rho.LLM, Rho.LLM.ReqLLM, Rho.Models, Rho.Usage): Anthropic, OpenAI, OpenAI Codex and Google, with subscription usage windows and per-model counters. The ChatGPT sign-in's models are the ones Codex lists for the account (Rho.Models.Codex, fetched and kept); a session on one it no longer accepts moves to its default with a notice.
• Auth (Rho.Auth, Rho.Auth.Login): Claude Pro/Max and ChatGPT (Codex) subscriptions through omp's OAuth PKCE flows, with refresh coordination and refresh-token rotation; or an API key for Anthropic, OpenAI or Gemini.
• Consult (Rho.Consult, Rho.Tools.Consult): one model asks another (Claude answers, Gemini pushes back): the ask_model tool for the lead model, Rho.Consult.run/3 for the host, and the answer handed back as that model's own message in the session.
• Pictures (Rho.Images): drawn on the user's ChatGPT sign-in, as Codex draws them (the hosted image_generation tool), from words and reference pictures; no API key, it counts against the subscription.
• Dyn (Rho.Dyn, optional): tools and screens the agent writes, compiles and runs on the device, one approved generation at a time, on probation and reverted when they crash.

Lineage

The loop, session format, compaction and sign-in flows are ports of pi (pi-agent-core, pi-ai, pi-coding-agent) as oh-my-pi (omp) runs them, first written in Elixir for Operator, an omp-style agent that runs on the phone. rho is that core taken out of Operator so other apps (Operator itself, and Bezalel, a Bible-study app) can share it. Comments name the pi source each piece follows.

Install

def deps do
  [{:rho, "~> 0.4"}]
end

A minimal host

rho has no OTP application callback (mob apps start their code by hand), so the host starts Rho.Supervisor in its own tree:

defmodule MyApp.Tools.Weather do
  @behaviour Rho.Tool

  @impl true
  def name, do: "weather"
  @impl true
  def description, do: "Today's weather for a city."
  @impl true
  def parameter_schema do
    %{
      "type" => "object",
      "properties" => %{"city" => %{"type" => "string"}},
      "required" => ["city"]
    }
  end

  @impl true
  def run(%{"city" => city}, _ctx), do: {:ok, "Sunny in #{city}."}
end

children = [
  {Rho.Supervisor, tools: [MyApp.Tools.Weather | Rho.ToolRegistry.builtin_tools()]}
]

Supervisor.start_link(children, strategy: :one_for_one)

:ok = Rho.Auth.put_api_key(:google, System.fetch_env!("GEMINI_API_KEY"))
{:ok, loop} = Rho.start_loop(model: "google:gemini-2.5-flash", system_prompt: "Be brief.")
:ok = Rho.Loop.subscribe(loop)
:ok = Rho.Loop.prompt(loop, "Weather in Lisbon?")

# The subscriber receives the run's events (`Rho.Events` lists them all):
# {:rho, session_id, %{type: :message_update, kind: :text, delta: "..."}} ...
# {:rho, session_id, %{type: :agent_end, reason: :done}}

A subscription sign-in instead: Rho.Auth.Login.begin(:anthropic) opens the provider's page (the callback comes back to a listener on localhost), then {:rho_login, :anthropic, :ok} arrives.

One model consulting another

The lead model asks another one through the ask_model tool (Rho.Tools.Consult; not a built-in, add it to the tools you offer), or the host consults one itself, e.g. for a critique after every reply, and hands the answer to the lead as that model's message:

# config: which models may be consulted, and the brief each purpose gets
config :rho,
  consult_models: ["google:gemini-3.1-pro-preview", "openai:gpt-5"],
  consult_system: %{"critique" => "Review this study answer: claims against the cited sources, ..."}

{:ok, %{text: critique, usage: _usage}} =
  Rho.Consult.run("google:gemini-3.1-pro-preview", "Review the last answer.",
    loop: loop, purpose: "critique", include_conversation: true)

:ok =
  Rho.Loop.follow_up(loop, critique,
    attribution: {:model, "google:gemini-3.1-pro-preview", "critique"},
    instruction: "Respond to each point: revise where it's right, keep your answer where it isn't, with reasons."
  )

With loop: the consult belongs to the session: its consult_start / consult_delta / consult_end events go to the loop's subscribers, its usage is recorded in the session (Rho.Session.totals/1 counts it) and against the daily cost cap, and Rho.Loop.stop/1 stops it. A provider without a key fails with {:error, {:signed_out, provider}}. The attributed message is stored as its own entry (Rho.Session.attribution/1 says which model and purpose) and sent to the lead marked as that model's, never the user's.

Pictures on the ChatGPT sign-in

{:ok, %{mime: "image/png", bytes: png, revised_prompt: _, action: "generate"}} =
  Rho.Images.generate("The ark of the covenant, two gold cherubim on its lid.",
    size: "1536x1024", quality: "low")

# draw from a picture: an edit
{:ok, %{action: "edit"} = edited} =
  Rho.Images.generate("The same ark, in a desert at dusk.", references: [{"image/png", png}])

It takes 20 to 60 seconds, so call it from a tool's task. Errors are Rho.LLM.error/0s (Rho.LLM.describe/1): {:signed_out, :openai_codex}, {:rate_limited, limit} with the used-up window's reset, and so on. Rho.Models.Codex lists the Codex models the account may use; the ChatGPT account refuses others (gpt-5.5, gpt-image-2).

What a host provides

Every coupling to the app around it is a behaviour or a config :rho key, each with a default that works on a computer (Rho.Config lists them all):

Rho.Supervisor also points llm_db at a model catalog trimmed to Anthropic, OpenAI and Google (Rho.LLMCatalog), on every platform: a phone doesn't ship llm_db's packaged one, and the trimmed one loads fast. A host that uses llm_db (or req_llm) for other providers starts it with llm_catalog: false.

Several accounts on one server

A host whose users keep their sign-ins elsewhere (a website whose accounts are phones) starts rho without the node's sign-ins and keeps each account's credentials in memory, in a Rho.Auth.Vault:

{Rho.Supervisor, tools: tools, auth: false}

{:ok, vault} =
  Rho.Auth.Vault.start_link(
    # rho refreshed a sign-in: send it back to where the account keeps it
    on_refresh: fn provider, creds -> MyApp.Link.rotated(account, provider, creds) end,
    # or ask that place to refresh it ({:ok, creds}), else :local
    refresher: fn provider -> MyApp.Link.refresh(account, provider) end
  )

:ok = Rho.Auth.Vault.put(vault, :anthropic, creds_from_the_phone)

Rho.start_loop(
  # the account's own directory: its sessions, usage and artifacts
  session: Rho.Session.new(Path.join(account_dir, "sessions"), model, account_dir),
  data_dir: account_dir,
  llm:
    {Rho.LLM.ReqLLM,
     credential: &Rho.Auth.Vault.credential(vault, &1),
     status: fn -> Rho.Auth.Vault.status(vault) end}
)

Rho.Session.size/1, read_from/3 and append_bytes/3 keep a copy of a session file in step by byte offset (whole lines, idempotent on a resend), so a host never reimplements the file layout.

Dyn: code the agent writes on the device

Rho.Dyn lets the agent change the app it runs in without a release: it writes Elixir tools (and, in a UI app, screens) in a staging copy with the dyn_* tools, and dyn_propose statically checks, compiles and selftests them as a new generation. Nothing runs until the human approves it with the screen lock; then it is on probation: 3 crashes in 60 s, or a launch that dies before it is stable, revert it to its parent, and two failed launches in a row start the next one in safe mode (no Dyn code loaded), so the fixed Core can always repair it. Generation n compiles the agent's Dyn.Foo as Dyn.G<n>.Foo, next to the running one rather than over it; old generations unload only once nothing runs their code. Activations and reverts change the loop's tools from its next model call (Rho.Dyn.Source, a Rho.ToolRegistry.Source).

It is off unless the host turns it on:

# config/config.exs
config :rho, :dyn,
  enabled: true,
  namespace: MyApp.Dyn,
  app: :my_app,
  core: [MyApp],
  allowed: [MyApp.Files],
  screens: Rho.Dyn.Screens.Mob

# the host's boot, once Rho.Supervisor is up (it starts the Keeper):
Rho.Dyn.boot()

Its seams (Rho.Dyn.Config documents each):

The default check keeps Dyn code to Mob's Elixir modules: Mob's native layer :mob_nif is banned (banned_erlang, and as a value in forging, so it can't be held in a variable and called), and the host's :gated and :allowed lists say which of Mob's modules Dyn code may use. A host whose Dyn code must call :mob_nif drops both: check: [banned_erlang: %{mob_nif: nil}, forging: %{mob_nif: nil}].

Threat model. The check is a best-effort deny-list against the model's mistakes (a built tool that crashes, hangs, or calls something it shouldn't by accident), not a sandbox against deliberately hostile code. Known ways around it: atoms or funs handed in as data, raw messages to OTP processes (a report_cb sent to :logger_proxy), modules the lists don't name (Logger.App, Logger.Backends.*, LoggerBackends), starting a child under a trusted supervisor or :alarm_handler, and CPU, memory or message floods; Rho.Dyn.Check keeps the list. A host with stronger needs must isolate Dyn code itself (another node or OS process).

Within that model, rho keeps a built tool's failures out of the processes that run the app (the loop, the Keeper, the logger). Like the check, these are best effort:

• Crashes are formatted where they happen (Rho.Untrusted): in the tool's task, the selftest or the compile, by a helper with a time and heap bound that dies with its caller. The loop, the Keeper and a proposal's caller only describe the reasons they receive, without calling an exception's message/1 or a protocol (Inspect, String.Chars, Jason.Encoder) a Dyn struct implements; integers past 1024 bits print as a placeholder. Crash events' reason is a string.
• Answers become plain data: a Dyn tool's result and details are turned into plain terms (structs as maps) in its own task.
• Declarations are read once: a tool's name, description, schema, timeout and concurrency are read in one bounded throwaway process and kept. A tool whose declaration fails is left out; one that ran over is read again after 1, 5 and 30 minutes, then stays out.
• Logs are described (Rho.Dyn.LogGuard, installed by the Keeper): a log event that holds a Dyn struct is turned into text before Elixir's translator sees it, so a Dyn process's crash report runs none of its code in :logger_proxy. It looks at most 10,000 terms; a bigger event passes through unchanged.
• Host processes: a host watches its own Dyn processes (a built screen, say) with Rho.Dyn.watch/2 and Rho.Dyn.unwatch/1; one that exits {:rho_crash, text} (Rho.Untrusted.crash/3) is reported with text.

Known limit: without LogGuard, a Dyn exception whose message/1 fails can make OTP drop Elixir's logger translator VM-wide. LogGuard keeps that call out of the translator, except for an event too big to check (more than 10,000 terms ahead of the Dyn term) or after Logger is restarted, which removes the filter.

On a phone, Dyn needs the Elixir compiler at run time: the app's build must ship :elixir's compiler modules and :compiler, so a slim build that strips them can't use Dyn.

Development

mix deps.get
mix format --check-formatted
mix credo --strict
mix compile --warnings-as-errors
mix test

Tests never reach a network: the model client is a scripted fake, and the OAuth and usage endpoints are answered in-process.

License

MIT, see LICENSE, which also carries pi's copyright notice for the ported parts.