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.

[jieyuexing]

Note

Drafted by Claude Opus 5.5 in Claude Code (via T3 Code); reviewed and posted by @jieyuexing.

+1. A real use case, and a request about which fields to include.

I coordinate from a T3 thread and send most work to other providers with delegate_task (Codex for implementation, Grok for bounded research and review, Claude for coordination). Because orchestrator_capabilities has no usage data, I run a separate local CLI before each delegation. It reads the same subscription windows that Usage → Limits shows and returns a suggested executor. I would like to drop that workaround and read the data from T3, which already collects it.

Running that CLI daily has shown that label + used percent + reset time is not enough to decide well. Everything below already exists in ServerProviderUsageLimits / ServerProviderUsageWindow, so the simplest version of this proposal could pass that object through unchanged:

• windowDurationMins / kind. The agent's choice depends on which window is exhausted. A 5-hour session window means it should wait and resume. A weekly window means it should hand the work to another provider. [Bug]: OpenCode Go usage limit fails threads as a generic provider error: no reset time, no auto-resume, not exposed to orchestrator MCP tools #16366 describes the same problem from the failure side: an orchestrator could not tell a 90-minute window from a 5-day one.
• Every window, keyed by its stable id. Claude's per-model weekly windows (seven_day_<model>) matter when the delegated model is that model. A single summary window can hide the window that will actually block the run.
• checkedAt. Without a sample time, an old 0% left from before a reset looks the same as a live one. My CLI treats a snapshot as unknown once it is older than a threshold, or once a reported resetsAt has passed. Agents need the timestamp to do the same.
• resetCredits (availableCount, nextExpiresAt). With a banked Codex credit, "redeem and continue" is often a better answer than rerouting. The agent can only suggest this if it can see the credit.
• unavailable.reason (unsupported vs probeFailed). "This account never reports limits" and "the probe failed this time" are different. Neither one should be read as having spare capacity.

I agree with the non-goals: no automatic fallback, and no change to canRunChildTask. Routing policy (thresholds, which task types may go to which provider, pacing) varies too much between users to belong in T3. The ask is only for read-only data.

Related: #16366 (OpenCode Go limit failures, which asks for the same exposure in its Expected section) and #15665.