Show provider usage limits in orchestrator_capabilities so agents can avoid rate-limited providers

[coygeek]

Summary

Include each provider instance's existing usage-limit state in the orchestrator_capabilities result, so an orchestrating agent can avoid delegating to a provider that is currently rate-limited or out of quota and pick another one.

Problem to solve

Agents choose a child provider from orchestrator_capabilities. Its per-provider constraints and canRunChildTask flags reflect only adapter presence, enabled and installed state, driver availability, provider status, and authentication. A provider whose account has hit its usage limit still reports canRunChildTask: true with no constraints. An orchestrator then delegates, the child fails with a durable rate-limit failure such as "Claude API rate limit reached. Try again later.", and nothing tells the agent when the limit resets, so it may keep routing work to the exhausted provider or retry blindly. The server already tracks this data: ServerProvider.usageLimits carries usage windows with usedPercent and resetsAt (updated from runtime rate-limit events), and threads record lastErrorClass and usageLimitResetAt after a usage-limit failure. The data is visible to people in the UI but not to agents.

Proposed behavior

Each provider entry in orchestrator_capabilities gains optional, read-only usage information derived from what the server already knows: for example the current usage windows (label, used percentage, reset time) and, when the instance's most recent child or thread failure was a usage-limit failure, the time it is expected to reset. When the provider does not report usage, the field states that it is unavailable rather than implying capacity. The existing canRunChildTask and canRunCrossProviderChildTask semantics, which also gate delegate_task, do not change.

Acceptance criteria

• With a provider instance whose usage snapshot reports a window, orchestrator_capabilities returns that window's label, used percentage, and reset time for the instance.
• After a delegated child fails with a usage-limit failure, a later orchestrator_capabilities call shows that the instance is limited and when it resets, until the reset time passes or a fresh usage snapshot clears it.
• A provider with no usage support reports the information as unavailable, and its canRunChildTask value is unchanged.
• delegate_task behavior and existing capability fields are unchanged for all providers.
• The orchestrator_capabilities tool description tells agents the usage fields exist and are advisory.

Affected area

apps/server/src/mcp/OrchestratorMcpService.ts (capabilities result built near providerConstraints at L218), the capability schema in packages/contracts/src/orchestratorMcp.ts, and the existing usage data in packages/contracts/src/server.ts (usageLimits at L280), packages/contracts/src/providerUsageLimits.ts, and packages/contracts/src/orchestrationV2.ts (lastErrorClass, usageLimitResetAt at L1793-1794).

Non-goals

• Automatic provider fallback or rerouting of delegated tasks.
• Changing which providers delegate_task accepts.
• New usage probing or polling; only already-collected data is exposed.
• Account rotation across multiple accounts of one provider (discussion [Feature]: Auto-select the account with the most remaining quota before starting a task #6923, draft PR feat(providers): new threads can rotate across a provider's accounts #16076).

Alternatives considered

• Make canRunChildTask false while a provider is limited: blocks delegation on advisory and possibly stale data, and changes a gating contract.
• Leave it to the agent to remember failures: each agent turn and each new thread loses that knowledge, and reset times are not exposed in the failure.

Supporting context

Current constraint logic is at OrchestratorMcpService.ts:218. Related open work: PR #15930 (capabilities re-probe providers that look unavailable), #15716 and #15992 (capabilities listing models disabled in settings). No existing request for agent-visible usage limits was found.