CrowdControl.Agent adapter for Oh My Pi (omp).

Launches omp --mode rpc, omp's newline-delimited JSON-RPC protocol over stdio, and normalizes its frames into CrowdControl.Protocol.message/0 so subscribers written against Claude Code work unchanged.

Wire mapping

omp acknowledges a prompt command before the turn runs, so the completion signal is agent_end — and only when isTerminal is not false, since a false means maintenance or async delivery will resume the session. An agent_end is turned into a Claude-shaped result map: "result" is the final assistant text, "total_cost_usd" the summed cost of the turn's assistant messages, plus "usage", "num_turns", "duration_ms" and "stop_reason".

A prompt that omp resolves locally — a slash command such as /tools — never produces an agent_end. It completes with agentInvoked: false, which maps to a result carrying "local_only" => true and an empty "result": the command's own text arrives separately as command_output frames, and decode_line/1 is stateless. Without this a local-only prompt would hang a collector until its deadline.

The adapter stays on protocol v1 (no negotiate_protocol), so an oversized logical frame is truncated by omp rather than chunked; :max_line_bytes on the session still bounds what a single line may cost.

Credentials

Everything below travels through the session's validated environment — a 0600 env file locally, the exec Env array remotely. Never argv, never ps.

:api_key and :api_url are Anthropic-specific shorthands inherited from CrowdControl.CLI; for any other hosted provider use :env with the variable omp documents for it.

Subscription passthrough

A session with no :custom_provider uses omp's real agent directory, so a /login you have already done applies with no configuration at all — that is the easiest way to bill sessions to a Claude subscription.

Two cases need help:

• No stored login (CI, a container, another user): mint a token with omp and pass it as :oauth_token.
• :custom_provider is in play: it relocates the agent directory (see below), which leaves the stored login behind. Add inherit_auth: true to the spec to link the real store back in, and the session can reach both its custom endpoint and Anthropic.

inherit_auth is opt-in rather than the default on purpose: it symlinks your OAuth store into a directory a session's own bash tool can read, while that session is talking to a third-party endpoint. Turn it on for endpoints you trust; leave it off for ones you do not.

Options

Shared with CrowdControl.CLI (Claude Code): :executable (default "omp"), :model, :system_prompt, :allowed_tools, :permission_mode, :resume, :continue, :add_dir, :no_session_persistence, :extra_args, :env, :api_key, :api_url.

:permission_mode is translated to omp's approval modes: "bypassPermissions" => yolo, "acceptEdits" => write, "default" => always-ask. "plan" has no approval-mode equivalent and raises; use extra_args: ["--plan-yolo"] if that is what you want.

omp-native options:

• :approval_mode - "always-ask", "write" or "yolo"; wins over :permission_mode
• :auto_approve - true to auto-approve every tool call
• :append_system_prompt - text (or file path) appended to the system prompt

• :thinking - "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | "auto"

• :provider, :service_tier, :profile, :max_time
• :cwd, :session_dir - paths (sanitized + expanded)
• :config, :hooks, :extensions - path or list of paths, one flag each
• :models, :skills - lists joined with ,
• :no_tools, :no_lsp, :no_pty, :no_extensions, :no_skills, :no_rules, :no_title, :advisor, :allow_home, :hide_thinking - booleans
• :streaming_behavior - "followUp" (default) or "steer"; how a prompt sent mid-turn is queued
• :agent_dir - path for PI_CODING_AGENT_DIR, the directory omp reads models.yml and config.yml from (sanitized + expanded)
• :custom_provider - declarative OpenAI-compatible endpoint; see below
• :sandbox_agent_dir - ship :custom_provider's rendered files into a remote sandbox instead of rendering them on the host; true for the default in-sandbox directory, or an absolute in-sandbox path. Needs CrowdControl.Backend.Sandboxd; see below
• :oauth_token - Claude subscription token; sets ANTHROPIC_OAUTH_TOKEN

Claude-Code-only options (:mcp_config, :strict_mcp_config, :agents, :plugin_dir, :settings, :settings_file, :settings_json, :setting_sources, :max_budget_usd, :session_id, :bare) have no omp equivalent and raise ArgumentError rather than being dropped silently. :include_partial_messages is accepted and ignored: RPC mode always streams deltas as message_update frames.

Custom providers (vLLM, LiteLLM, any OpenAI-compatible endpoint)

omp resolves a provider's baseUrl from models.yml under its agent directory — there is no CLI flag for it. :custom_provider renders that file into a private 0700 temp directory and points PI_CODING_AGENT_DIR at it:

CrowdControl.run("Explain this repo",
  agent: :omp,
  custom_provider: [base_url: "http://10.0.0.5:8000/v1"],
  model: "vllm/Qwen/Qwen3-Coder-30B"
)

Spec keys:

• :base_url - required, the OpenAI-compatible endpoint
• :id - provider id, default "vllm". omp has a built-in vllm provider that reads max_model_len from /v1/models; any other id is a plain custom provider. The id is the provider/ prefix in :model.
• :api - default "openai-completions"; use "openai-responses" for a server exposing /v1/responses, or "anthropic-messages"
• :api_key - provider credential. Never written to models.yml: it is passed through the same validated environment channel as :api_key (a 0600 env file locally, the exec Env array remotely), and the config references it by variable name. Omit it for an unauthenticated server, which renders auth: none.
• :api_key_env - name of that variable, default "OMP_CUSTOM_PROVIDER_KEY"
• :models - explicit model list, each [id: ..., name: ..., context_window: ..., max_tokens: ..., reasoning: true | false, input: ["text", "image"]]. Omit to discover models from the server's /v1/models instead.
• :headers - extra request headers as a string-keyed map
• :inherit_auth - true to link omp's stored-login database (~/.omp/agent/agent.db) into the generated directory, so the session keeps the logins omp already has despite the relocation. Accepts a path to a specific agent directory instead of true. Off by default — see "Subscription passthrough" above for the trade-off.

The directory is content-addressed, so every session in a fan-out sharing one spec shares one directory rather than writing N copies. Build it yourself with provider_dir!/1 and pass :agent_dir when you want to own the lifecycle (and remove_provider_dir/1 to delete it).

Custom providers on a remote sandbox

A host temp directory is not visible inside a sandbox, so a rendered models.yml has to get there some other way. Which backends solve that and which still leave it to you:

• CrowdControl.Backend.Sandboxd — solved. Pass sandbox_agent_dir: true and the rendered file is written into the sandbox at /tmp/cc-omp-agent/models.yml, mode 0600, over the agent's PUT /v1/files — after the sandbox exists and before the CLI starts — with PI_CODING_AGENT_DIR pointing there. Pass an absolute in-sandbox path instead of true to choose the directory. Nothing at all is rendered on the host on this path.
• CrowdControl.Backend.Docker and CrowdControl.Backend.Kubernetes — still yours. Neither has a file-transfer channel, so the directory has to be baked into the image or mounted in (a bind mount, a ConfigMap); render it with provider_dir!/1 and pass :agent_dir naming the path it has inside the container, not on the host.
• CrowdControl.Backend.Local — never a problem, since the host is the sandbox and :custom_provider alone already works.

:inherit_auth is refused together with :sandbox_agent_dir. omp's auth store is a host file it refreshes in place, so a symlink means nothing across a substrate boundary and a copy would strand refreshed tokens in the sandbox — while handing a live subscription credential to the untrusted code the sandbox exists to contain. Use :oauth_token to bill a subscription from a sandboxed session.