api-proxy: document and expose /reflect endpoint for configuration introspection

[lpcox]

Summary

The api-proxy sidecar (enabled via --enable-api-proxy) already exposes a
GET /reflect endpoint on its management port (10000) that returns a complete
snapshot of everything the proxy knows about its configuration: every LLM provider
endpoint, its availability, its cached model list, and whether startup model
discovery has finished.

This issue tracks documenting that endpoint and any follow-on improvements.

Current behaviour

GET http://api-proxy:10000/reflect (reachable inside the agent container)
returns a JSON payload such as:

{
  "endpoints": [
    {
      "provider": "openai",
      "port": 10000,
      "base_url": "http://api-proxy:10000",
      "configured": true,
      "models": ["gpt-4o", "gpt-4o-mini", "o1", "..."],
      "models_url": "http://api-proxy:10000/v1/models"
    },
    {
      "provider": "anthropic",
      "port": 10001,
      "base_url": "http://api-proxy:10001",
      "configured": true,
      "models": ["claude-opus-4-5", "claude-sonnet-4-5", "..."],
      "models_url": "http://api-proxy:10001/v1/models"
    },
    {
      "provider": "copilot",
      "port": 10002,
      "base_url": "http://api-proxy:10002",
      "configured": false,
      "models": null,
      "models_url": "http://api-proxy:10002/models"
    },
    {
      "provider": "gemini",
      "port": 10003,
      "base_url": "http://api-proxy:10003",
      "configured": false,
      "models": null,
      "models_url": "http://api-proxy:10003/v1beta/models"
    },
    {
      "provider": "opencode",
      "port": 10004,
      "base_url": "http://api-proxy:10004",
      "configured": true,
      "models": null,
      "models_url": null
    }
  ],
  "models_fetch_complete": true
}

Field reference

Field	Type	Description
endpoints[].provider	string	Provider name: openai, anthropic, copilot, gemini, opencode
endpoints[].port	number	Port the proxy listens on for this provider
endpoints[].base_url	string	Base URL to use as OPENAI_BASE_URL / ANTHROPIC_BASE_URL etc.
endpoints[].configured	boolean	true if the provider's API key/token is present
endpoints[].models	string[] | null	Cached model IDs fetched at startup; null if not yet fetched or N/A
endpoints[].models_url	string | null	URL to query live models; null for providers that delegate (e.g. opencode)
models_fetch_complete	boolean	true once the startup model-discovery pass has finished for all configured providers

Use cases

• Dynamic model selection — agent harnesses can call /reflect at startup to
  discover which providers are configured and pick the best available model without
  hardcoding provider assumptions.
• Multi-provider orchestration — a workflow can iterate the endpoints array
  and fan out tasks to multiple providers in parallel.
• Readiness gate — poll /reflect until models_fetch_complete: true before
  submitting the first request, ensuring model lists are warm.
• Debugging — quickly verify which API keys were injected and what models were
  discovered without inspecting the host environment.

Proposed work

1. Document /reflect in the api-proxy documentation (containers/api-proxy/README.md,
   docs/environment.md, or a new docs/api-proxy.md).
2. Expose models_fetch_complete in the /health response as a readiness
   signal alongside the existing key-validation fields.
3. Consider a --wait-for-models awf CLI flag (or document a polling recipe)
   so callers can block until models_fetch_complete: true before the agent
   command is launched.
4. Fix port table in AGENTS.md — port 10003 (Gemini) is currently in use
   but not listed in the Architecture section port table (10000/10001/10002/10004
   are listed). Update docs to include port 10003.

References

• Implementation: containers/api-proxy/server.js — reflectEndpoints() (~line 1365)
  and handleManagementEndpoint() (~line 1439)
• AGENTS.md — Architecture section, API Proxy Sidecar description
• docs/environment.md — environment variable configuration