Ping the server

List configured agents merged with their current state

Return the current external-agents state file (per-agent healthy/not_installed/needs_auth/quota_exhausted/errored_transient with metadata)

Probe a specific agent by id; runs an install-check and updates the state file. Returns the new state.

Persist an API-key env variable so the next dispatch (and future sessions) see it. Writes to ~/.local/state/external-agents/keys.env (mode 0600).

Pick up to N distinct healthy candidates by round-robin (preference_order + last_used_at). Optional min_distinct_providers enforces cross-provider diversity.

ROUTING NOTE: default filter is tier='weak' — that is intentional. Most atomic tasks (single-file edits, refactors, glue code, summaries, format conversions, well-scoped fixes) get the same quality answer from a weak-tier free-tier model as from Claude Opus or Codex Pro, in a fraction of the time and cost. Reach for strong-tier (filter tier='strong') ONLY when the task actually needs deep reasoning: multi-step debugging, architecture decisions, ambiguous requirements, novel algorithms. Frontier ≠ better output for the long tail of routine work; often it is slower with no quality gain. Be smart, not lavish.

Run a specific agent by id with a prompt. transport ('generate' | 'cli') overrides the default (generate preferred when entry declares it). escalate_to_pro=true uses the same-provider strong-tier entry instead.

ROUTING NOTE: for the same task, weak-tier free-tier models (Gemini flash, Groq llama, DeepSeek, OpenRouter :free) are usually correct AND fast enough. Use dispatch against Claude Opus, Codex Pro, or any strong-tier subscription model ONLY when the task genuinely needs frontier capability. escalate_to_pro is a retry lever, not a default. If a weak agent's output is wrong, first ask whether the SPEC was ambiguous (fix the spec, re-dispatch weak) before escalating tier — reaching for stronger models hides prompt-engineering failures behind expensive compute.

Aggregate dispatch telemetry from ~/.local/state/external-agents/dispatch-log.jsonl. Returns per-agent counts, tokens, outcomes; per-transport totals.