feat(provider-concurrency): implement per-provider in-memory concurrency limits with oldest-agent-first scheduling

1 files changed, 53 insertions, 0 deletions

diff --git a/packages/transport-contract/src/index.ts b/packages/transport-contract/src/index.ts
index 6a9a29f..400d9d5 100644
--- a/packages/transport-contract/src/index.ts
+++ b/packages/transport-contract/src/index.ts
@@ -985,3 +985,56 @@ export interface HeartbeatRunsResponse {
 export interface StopHeartbeatRunResponse {
   readonly ok: true;
 }
+
+// ─── Provider concurrency limits ──────────────────────────────────────────────
+
+/**
+ * Response of `GET /concurrency/limits` — all providers with configured
+ * concurrency limits. Each entry pairs a provider id (e.g. "umans",
+ * "openai-compat") with its maximum concurrent in-flight requests. Providers
+ * not listed here have no limit (unlimited).
+ */
+export interface ConcurrencyLimitsResponse {
+  readonly limits: readonly { readonly providerId: string; readonly limit: number }[];
+}
+
+/**
+ * Body of `PUT /concurrency/limits/:providerId` — set or update the concurrency
+ * limit for a provider. `limit` must be a positive integer. When a limit is
+ * set, requests beyond the limit queue (oldest-agent-first) rather than being
+ * sent immediately.
+ */
+export interface SetConcurrencyLimitRequest {
+  readonly limit: number;
+}
+
+/** Response of `GET/PUT /concurrency/limits/:providerId` — the configured limit. */
+export interface ConcurrencyLimitResponse {
+  readonly providerId: string;
+  readonly limit: number;
+}
+
+/**
+ * One provider's live concurrency status.
+ *
+ * - `inFlight`: how many slots are currently held (tokens being generated).
+ * - `queued`: how many agents are waiting for a slot.
+ * - `paused`: whether the queue is paused due to a 429 backoff.
+ * - `pausedUntil`: when the pause expires (epoch-ms), present only when paused.
+ */
+export interface ConcurrencyStatusEntry {
+  readonly providerId: string;
+  readonly limit: number;
+  readonly inFlight: number;
+  readonly queued: number;
+  readonly paused: boolean;
+  readonly pausedUntil?: number;
+}
+
+/**
+ * Response of `GET /concurrency/status` — live status for every provider with a
+ * configured limit. Providers without a limit are absent (they are unlimited).
+ */
+export interface ConcurrencyStatusResponse {
+  readonly providers: readonly ConcurrencyStatusEntry[];
+}