Agent Switcher Branch

Final Design and Change Summary

This document summarizes the meaningful product and engineering changes in the agent-switcher work. It intentionally skips the negligible formatting/merge commits and omits the internal removed-counts detail.

PR: https://github.com/aoagents/ReverbCode/pull/276

Agent catalog Authorization-aware selection Safe orchestrator replacement Cached daemon-level data

Executive Summary

The branch introduces a first-class agent catalog and agent switching workflow. AO now knows which agent adapters it supports, which are installed on the machine, and which are currently usable because they are logged in or otherwise authorized.

The frontend uses this catalog to let users configure worker and orchestrator agents per project. Unavailable agents remain visible with clear status labels such as Needs auth and Needs install, so users understand why an agent cannot be selected.

Primary user outcome: users can switch project worker/orchestrator agents without guessing which CLIs are installed, logged in, or safe to use for orchestrator replacement.

Problem Addressed

  • Some agents were effectively hardcoded in the UI instead of coming from the daemon catalog.
  • Project settings did not have a clear machine-level view of available agent adapters.
  • Users could not easily distinguish available agents from installed-but-not-logged-in agents.
  • If AO starts an unauthenticated agent, the agent can ask for login during session runtime. Logging in there may create a new native agent session that does not receive AO's system prompt.
  • Changing the orchestrator agent needed safer replacement and retry behavior.
  • Agent catalog discovery should not run repeatedly for every project settings page.

Design Direction

  • Treat agent inventory as daemon-level data, not project-level data.
  • Make unavailable agents visible but non-selectable with a reason.
  • Cache catalog data globally after daemon readiness.
  • Provide explicit refresh through Reload agents after external login/install changes.
  • Keep orchestrator replacement conservative if the new agent cannot start.

Main Workflow

1

Daemon Builds Catalog

The backend lists supported adapters and probes local launch/auth availability for each agent.

2

Frontend Caches It

The shell fetches /api/v1/agents after the daemon is ready and stores it in a shared query.

3

Settings Reuses It

Project Settings reads the shared catalog for worker and orchestrator agent dropdowns.

4

Replacement Is Safe

Orchestrator switching checks current state and preserves/retries safely when replacement fails.

Backend Changes

  • Added an agent catalog endpoint: GET /api/v1/agents.
  • Added a backend service that returns supported, installed, and authorized agents.
  • Added auth probes for supported agent adapters.
  • Extended the agent port contract to support authorization status checks.
  • Updated OpenAPI generation and frontend schema output for the catalog contract.
  • Fixed daemon wiring so project services receive the configured default agent harness.

Frontend Changes

  • Added useAgentsQuery as the shared agent catalog query.
  • Fetches the agent catalog once after daemon readiness instead of once per project settings page.
  • Added Reload agents for refreshing after external login or install changes.
  • Added worker/orchestrator agent selectors to Project Settings.
  • Shows Needs auth and Needs install in dropdown options.
  • Added dashboard guidance when no authorized agents are available.

Agent Dropdown Behavior

Agent State Dropdown Treatment User Meaning
Authorized Visible and selectable The agent can be used for worker or orchestrator sessions.
Installed but not authorized Visible, disabled, labeled Needs auth The CLI exists, but the user needs to log in before AO can use it.
Supported but not installed Visible, disabled, labeled Needs install AO supports the agent, but the binary was not detected on this machine.
Previously configured but unavailable Kept visible with a warning The current project config is preserved, but the user is told why it cannot run now.
Dropdown statuses are intentionally visible so users do not have to infer why an orchestrator or worker agent cannot be selected.

Dashboard Guidance

When no authorized agents are available, the dashboard shows setup guidance before the user has to open Project Settings.

  • If installed agents need login, the message names them.
  • If no supported agents are installed, the message asks the user to install and log in.
  • The message includes Reload agents to refresh after external setup.

Example: Log in to Cursor, GitHub Copilot, and opencode, then reload agents.

Catalog Caching

The catalog is cached globally because it describes the local daemon/machine, not a single project. Project Settings now reads from shared cache instead of fetching the same catalog repeatedly.

  • useAgentsQuery owns the query key and fetch behavior.
  • The shell warms the query after daemon readiness.
  • The query is invalidated when the daemon ready port changes.
  • Reload agents handles external login/install changes.

Safe Orchestrator Replacement

The branch improves the flow for changing a project's orchestrator agent. The system compares the saved desired agent with the live orchestrator, checks whether the current orchestrator can be replaced, and handles failed replacement without discarding the old working session too eagerly.

Scenario Behavior
Orchestrator agent changes while current orchestrator is active Save is blocked until the orchestrator is idle enough to replace safely.
New orchestrator starts successfully Config is saved and the UI reports that the orchestrator restarted.
New orchestrator fails to start The previous orchestrator is kept alive and the UI exposes a retry path.
Saved config differs from running orchestrator Project Settings shows replacement-pending state until retry succeeds.

Included Commits

  • 36cf91f Agent catalog API and project settings integration.
  • 8088d6c Agent authorization checks and frontend status handling.
  • 70a76bc Simpler orchestrator replacement retry flow.
  • f4389f1 Improved orchestrator agent change detection.
  • a6ee5af Agent catalog cache and final API/frontend cleanup.

Skipped Here

  • Merge commit from main.
  • Import formatting and route-definition refactor.
  • Internal removed-counts implementation details.

Verification

  • Backend agent catalog tests.
  • Backend API spec generation tests.
  • Backend controller tests.
  • Frontend typecheck.
  • Project Settings and Sessions Board tests.