feat(http)!: require host_config.providers; fail loudly on misconfig

[manojp99]

Why

During a recent DTU exploration, we surfaced a set of backlog items (#4 #5 #6 #7 #8) around cryptic startup behavior in amplifier-agent serve chat-completions:

• The server iterated a hardcoded KNOWN_PROVIDERS list and silently skipped providers whose credentials were missing or modules were not installed.
• When nothing loaded, it fell back to a useless placeholder "amplifier" model entry.
• Requests with an unknown model were silently routed to whichever provider happened to load first, then failed with an upstream not_found_error embedded in delta.content 4 seconds later.
• stream: false was silently ignored.
• Upstream errors raised during session initialization were embedded in SSE delta.content at HTTP 200, making them impossible to distinguish from successful responses at the client level.

This PR resolves all five issues with a single clean redesign: explicit per-provider config + fail loudly on any boot-time issue.

It also bundles the operational lifecycle commands that close the story — without them, users have to pkill -f "amplifier-agent serve" every iteration, and can't tell whether the server is running, hung, or dead. Same audience, complementary change, single review.

---

Changed

• Breaking (server mode only): amplifier-agent serve chat-completions now requires host_config.providers to be a non-empty dict. Any provider declared there that cannot initialize (missing credentials, module not installed, list_models() raises, returns 0 models) causes the server to exit 2 with a structured error listing every problem. The previous behavior — iterating a hardcoded KNOWN_PROVIDERS list, silently skipping unreachable providers, and falling back to an unusable placeholder model — is gone. Single-turn mode (amplifier-agent run) is unaffected; the provider (singular) block continues to work for it.

• POST /v1/chat/completions now validates model against the served registry. Requests with an unknown model return HTTP 400 {"error": {"code": "unknown_model", ...}} immediately, instead of being silently routed to whichever provider loaded first and failing 4 seconds later with an upstream not_found_error embedded in delta.content.

• stream: false is now honored. Requests with that flag return a single JSON body; only stream: true (or absent) uses SSE.

• Upstream errors raised before any content chunks are emitted now surface as HTTP 502 with a structured OpenAI-shape error envelope, instead of being embedded inside delta.content of a 200 SSE response.

• /v1/models no longer falls back to a placeholder {"id": "amplifier", ...} entry. The lifespan now guarantees served_models_registry is non-empty (or the server exits at boot), so the fallback was unreachable in practice.

Added

• host_config.providers (plural) registry — declares which providers the server-mode lifespan loads and how to instantiate each. Schema: providers: {<provider_id>: {module?: str, config?: dict}}. The module defaults to the provider_id when omitted. Each provider's config is passed through as the extra_config arg to list_provider_models() and then to the provider module's constructor.

Lifecycle commands

Adds serve status / stop / restart operational commands. State persisted at ~/.amplifier-agent/state/serve.json (mode 0600, parent dir 0700; api_key is sensitive — never logged). Status reports running/stale/not-running plus served-model counts by provider; stop honors graceful shutdown with optional --force and --timeout; restart identity-restarts from the stored launch args (host, port, api-key, workspace, host_config).

amplifier-agent serve status

Reports whether the server is running, probes GET /v1/models over the wire, and self-cleans stale state files (PID gone). Exits 0 on healthy, 1 when unreachable.

amplifier-agent serve stop [--force] [--timeout SECONDS]

Sends SIGTERM with a 5s graceful-exit window. Escalates to SIGKILL on timeout or when --force is given.

amplifier-agent serve restart

Identity restart — captures host, port, api-key, workspace, and host_config_path from the state file, stops the old server, and re-launches as a detached background process.

Internal

• New _validate_providers_registry() in amplifier_agent_lib/config/loader.py enforces the closed schema for the new block.
• HTTP-face tests introduced from scratch under tests/http/ covering lifespan boot scenarios and chat-completions validation.
• New src/amplifier_agent_cli/admin/serve_lifecycle.py — single owner of state file path and schema. Callers go through read_state_file, write_state_file, remove_state_file.
• ServerConfig gains host and port fields so the lifespan can write them to the state file without re-parsing CLI flags.

Migration

For server-mode users on <= 0.8.0: add a providers block to your host_config.json. Minimum to keep working with just Anthropic:

{
  "providers": {
    "anthropic": {}
  }
}

Multi-provider example:

{
  "providers": {
    "anthropic": {},
    "openai":    {"config": {"base_url": "https://api.openai.com/v1"}}
  }
}

If you don't pass host_config.providers, the server will exit at boot with a clear error message rather than running in a broken half-state.

---

Test Evidence

uv run pytest tests/config/ -q → 47 passed (no regressions)
uv run pytest tests/http/ -q  → 13 passed (all new tests green)
uv run pytest tests/cli/test_serve_lifecycle.py -q → 18 passed (all new)
ruff check + ruff format + pyright on all modified source files: clean