agent-relay-runner 0.74.0 → 0.76.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.74.0",
+  "version": "0.76.0",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
     "directory": "runner"
   },
   "dependencies": {
-    "agent-relay-sdk": "0.2.49"
+    "agent-relay-sdk": "0.2.51"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-relay-runner",
   "description": "Thin Agent Relay runner bridge for Claude Code",
-  "version": "0.74.0",
+  "version": "0.76.0",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/src/adapters/codex-client.ts

@@ -74,6 +74,11 @@ interface ThreadLoadedListResponse {
   nextCursor: string | null;
 }
 
+interface AccountRateLimitsResponse {
+  rateLimits?: unknown;
+  rate_limits?: unknown;
+}
+
 export const CODEX_APP_CLIENT_EVENT_CAP = 5_000;
 
 export class CodexAppClient {
@@ -193,6 +198,10 @@ export class CodexAppClient {
     return this.request<Record<string, never>>("turn/interrupt", { threadId, turnId });
   }
 
+  async accountRateLimitsRead(): Promise<AccountRateLimitsResponse> {
+    return this.request<AccountRateLimitsResponse>("account/rateLimits/read");
+  }
+
   respondToServerRequest(id: JsonRpcId, result: unknown): void {
     if (!this.connected) {
       throw new Error("websocket not connected");

package/src/quota.ts

@@ -0,0 +1,283 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { ContextProbeMetrics, QuotaState, QuotaWindowName } from "agent-relay-sdk";
+import { errMessage, isRecord, quotaStateFromProbeMetrics, stringValue } from "agent-relay-sdk";
+import type { ManagedProcess } from "./adapter";
+
+const CLAUDE_USAGE_URL = "https://api.anthropic.com/api/oauth/usage";
+const CLAUDE_OAUTH_BETA = "oauth-2025-04-20";
+const QUOTA_POLL_INTERVAL_MS = 15 * 60 * 1000;
+const QUOTA_FAILURE_LOG_INTERVAL_MS = 5 * 60 * 1000;
+
+type CodexQuotaClient = {
+  isConnected?: () => boolean;
+  accountRateLimitsRead?: () => Promise<unknown>;
+};
+
+export class RunnerQuotaPoller {
+  private quotaState?: QuotaState;
+  private timer?: Timer;
+  private inFlight = false;
+  private active = false;
+  private lastLog?: { key: string; at: number };
+
+  constructor(private readonly options: {
+    provider: string;
+    agentId: string;
+    getProcess: () => ManagedProcess | undefined;
+    onUpdate: () => void;
+    log: (message: string) => void;
+  }) {}
+
+  get current(): QuotaState | undefined {
+    return this.quotaState;
+  }
+
+  start(): void {
+    this.stop();
+    if (!quotaProviderSupported(this.options.provider)) return;
+    this.active = true;
+    void this.refresh();
+  }
+
+  stop(): void {
+    this.active = false;
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = undefined;
+  }
+
+  clear(): void {
+    this.quotaState = undefined;
+  }
+
+  private schedule(delayMs = QUOTA_POLL_INTERVAL_MS): void {
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = undefined;
+    if (!this.active || !quotaProviderSupported(this.options.provider)) return;
+    this.timer = setTimeout(() => {
+      this.timer = undefined;
+      void this.refresh();
+    }, Math.max(1_000, delayMs));
+  }
+
+  private async refresh(): Promise<void> {
+    if (this.inFlight) return;
+    this.inFlight = true;
+    try {
+      const quota = await collectRunnerQuotaState({
+        provider: this.options.provider,
+        agentId: this.options.agentId,
+        process: this.options.getProcess(),
+      });
+      if (quota && this.active) {
+        this.quotaState = quota;
+        this.options.onUpdate();
+      }
+      this.schedule();
+    } catch (error) {
+      const retryAfterMs = quotaRetryAfterMs(error);
+      if (this.active) this.logFailure(error, retryAfterMs);
+      this.schedule(retryAfterMs ?? QUOTA_POLL_INTERVAL_MS);
+    } finally {
+      this.inFlight = false;
+    }
+  }
+
+  private logFailure(error: unknown, retryAfterMs: number | undefined): void {
+    const key = retryAfterMs !== undefined ? `retry-after:${retryAfterMs}` : errMessage(error);
+    const now = Date.now();
+    if (this.lastLog?.key === key && now - this.lastLog.at < QUOTA_FAILURE_LOG_INTERVAL_MS) return;
+    this.lastLog = { key, at: now };
+    const suffix = retryAfterMs !== undefined ? `; retrying in ${Math.round(retryAfterMs / 1000)}s` : "";
+    this.options.log(`quota refresh failed${suffix}: ${errMessage(error)}`);
+  }
+}
+
+export class QuotaRetryAfterError extends Error {
+  constructor(readonly retryAfterMs: number, message = "quota source requested retry backoff") {
+    super(message);
+    this.name = "QuotaRetryAfterError";
+  }
+}
+
+export function quotaRetryAfterMs(error: unknown): number | undefined {
+  return error instanceof QuotaRetryAfterError ? error.retryAfterMs : undefined;
+}
+
+export async function collectRunnerQuotaState(input: {
+  provider: string;
+  agentId: string;
+  process?: ManagedProcess;
+}): Promise<QuotaState | undefined> {
+  if (input.provider === "claude") return collectClaudeQuotaState({ agentId: input.agentId });
+  if (input.provider !== "codex") return undefined;
+  const client = input.process?.meta?.client as CodexQuotaClient | undefined;
+  if (!client?.isConnected?.() || typeof client.accountRateLimitsRead !== "function") return undefined;
+  return collectCodexQuotaState({
+    agentId: codexProcessAgentId(input.process, input.agentId),
+    rateLimitsRead: () => client.accountRateLimitsRead!(),
+  });
+}
+
+export async function collectClaudeQuotaState(options: {
+  agentId: string;
+  credentialsPath?: string;
+  fetchImpl?: typeof fetch;
+  now?: number;
+}): Promise<QuotaState | undefined> {
+  const accessToken = await readClaudeOAuthAccessToken(options.credentialsPath ?? defaultClaudeCredentialsPath());
+  if (!accessToken) return undefined;
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const response = await fetchImpl(CLAUDE_USAGE_URL, {
+    method: "GET",
+    headers: {
+      authorization: `Bearer ${accessToken}`,
+      "anthropic-beta": CLAUDE_OAUTH_BETA,
+    },
+    signal: AbortSignal.timeout(10_000),
+  });
+  if (response.status === 429) {
+    throw new QuotaRetryAfterError(retryAfterHeaderMs(response.headers.get("retry-after")) ?? 60_000, "Claude quota source returned 429");
+  }
+  if (!response.ok) return undefined;
+  return claudeUsageQuotaState(await response.json(), options.agentId, options.now ?? Date.now());
+}
+
+export function claudeUsageQuotaState(payload: unknown, agentId: string, now = Date.now()): QuotaState | undefined {
+  return quotaStateFromProbeMetrics({
+    agentId,
+    contextPercent: 0,
+    quotaWindows: [
+      quotaWindowFromAnthropicUsage("five_hour", payload),
+      quotaWindowFromAnthropicUsage("seven_day", payload),
+    ].filter((window): window is NonNullable<ContextProbeMetrics["quotaWindows"]>[number] => Boolean(window)),
+    source: "api",
+    confidence: "reported",
+    timestamp: now,
+  });
+}
+
+export async function collectCodexQuotaState(input: {
+  agentId: string;
+  rateLimitsRead: () => Promise<unknown>;
+  now?: number;
+}): Promise<QuotaState | undefined> {
+  try {
+    return codexRateLimitsQuotaState(await input.rateLimitsRead(), input.agentId, input.now ?? Date.now());
+  } catch (error) {
+    const retryAfter = codexRetryAfterMs(error);
+    if (retryAfter !== undefined) throw new QuotaRetryAfterError(retryAfter, "Codex quota source returned 429");
+    throw error;
+  }
+}
+
+export function codexRateLimitsQuotaState(payload: unknown, agentId: string, now = Date.now()): QuotaState | undefined {
+  const rateLimits = isRecord(payload) && isRecord(payload.rateLimits) ? payload.rateLimits
+    : isRecord(payload) && isRecord(payload.rate_limits) ? payload.rate_limits
+    : payload;
+  return quotaStateFromProbeMetrics({
+    agentId,
+    contextPercent: 0,
+    quotaWindows: [
+      quotaWindowFromCodexRateLimit("primary", rateLimits),
+      quotaWindowFromCodexRateLimit("secondary", rateLimits),
+    ].filter((window): window is NonNullable<ContextProbeMetrics["quotaWindows"]>[number] => Boolean(window)),
+    source: "api",
+    confidence: "reported",
+    timestamp: now,
+  });
+}
+
+function defaultClaudeCredentialsPath(): string {
+  return join(homedir(), ".claude", ".credentials.json");
+}
+
+function quotaProviderSupported(provider: string): boolean {
+  return provider === "claude" || provider === "codex";
+}
+
+function codexProcessAgentId(process: ManagedProcess | undefined, fallback: string): string {
+  const config = isRecord(process?.meta?.config) ? process.meta.config : undefined;
+  return stringValue(config?.agentId) ?? fallback;
+}
+
+async function readClaudeOAuthAccessToken(path: string): Promise<string | undefined> {
+  try {
+    const parsed = JSON.parse(await readFile(path, "utf8")) as unknown;
+    const oauth = isRecord(parsed) && isRecord(parsed.claudeAiOauth) ? parsed.claudeAiOauth : undefined;
+    const token = oauth?.accessToken;
+    return typeof token === "string" && token.trim() ? token : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function quotaWindowFromAnthropicUsage(name: QuotaWindowName, payload: unknown): NonNullable<ContextProbeMetrics["quotaWindows"]>[number] | undefined {
+  if (!isRecord(payload)) return undefined;
+  const raw = isRecord(payload[name]) ? payload[name] : undefined;
+  const utilization = normalizePercentLike(raw?.utilization);
+  if (utilization === undefined) return undefined;
+  return {
+    name,
+    utilization,
+    ...(resetValueMs(raw?.resets_at) !== undefined ? { resetsAt: resetValueMs(raw?.resets_at)! } : {}),
+    unit: "%",
+  };
+}
+
+function quotaWindowFromCodexRateLimit(name: QuotaWindowName, payload: unknown): NonNullable<ContextProbeMetrics["quotaWindows"]>[number] | undefined {
+  if (!isRecord(payload)) return undefined;
+  const raw = isRecord(payload[name]) ? payload[name] : undefined;
+  const utilization = normalizePercentLike(raw?.usedPercent ?? raw?.used_percent ?? raw?.utilization);
+  if (utilization === undefined) return undefined;
+  return {
+    name,
+    utilization,
+    ...(resetValueMs(raw?.resetsAt ?? raw?.resets_at) !== undefined ? { resetsAt: resetValueMs(raw?.resetsAt ?? raw?.resets_at)! } : {}),
+    unit: "%",
+  };
+}
+
+function normalizePercentLike(value: unknown): number | undefined {
+  const number = numberValue(value);
+  if (number === undefined) return undefined;
+  const fraction = number > 1 ? number / 100 : number;
+  return Math.max(0, Math.min(1, fraction));
+}
+
+function resetValueMs(value: unknown): number | undefined {
+  const number = numberValue(value);
+  if (number !== undefined) return number < 10_000_000_000 ? number * 1000 : number;
+  if (typeof value !== "string" || !value.trim()) return undefined;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function retryAfterHeaderMs(value: string | null): number | undefined {
+  if (!value) return undefined;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1000;
+  const date = Date.parse(value);
+  if (!Number.isFinite(date)) return undefined;
+  return Math.max(0, date - Date.now());
+}
+
+function codexRetryAfterMs(error: unknown): number | undefined {
+  const message = errMessage(error);
+  if (!/\b429\b/.test(message)) return undefined;
+  return retryAfterHeaderMs(retryAfterFromText(message)) ?? 60_000;
+}
+
+function retryAfterFromText(message: string): string | null {
+  return /retry-after[:=]\s*([^,;\s]+)/i.exec(message)?.[1] ?? null;
+}
+
+function numberValue(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+  }
+  return undefined;
+}

package/src/runner-core.ts

@@ -4,7 +4,7 @@ import { readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import type { AgentLifecycle, AgentProfile, ContextState, Message, MessageSessionMeta, SendMessageInput, TaskStatusInput, WorkspaceMetadata } from "agent-relay-sdk";
 import { errMessage, RelayBusClient, RelayHttpClient } from "agent-relay-sdk";
-import { contextStateFromProbeMetrics, readContextProbeState } from "agent-relay-sdk/context-probe";
+import { contextStateFromProbeMetrics, quotaStateFromProbeMetrics, readContextProbeState } from "agent-relay-sdk/context-probe";
 import { providerAttachmentText, providerMessageText } from "./adapter";
 import type { ManagedProcess, ProviderAdapter, ProviderConfig, ProviderPermissionDecision, ProviderPermissionDecisionInput, ProviderSessionEvent, ProviderStatusUpdate, RunnerSpawnConfig, SemanticStatus, TerminalAttachSpec } from "./adapter";
 import { messagesWithCachedAttachments } from "./attachment-cache";
@@ -24,6 +24,7 @@ import { RunnerInsights } from "./runner-insights";
 import { BusyReconciler } from "./busy-reconciler";
 import { publishCapturedResponse } from "./response-capture-report";
 import { runnerLaunchInjectionSessionEvents, type RunnerRelayInjectionEvent } from "./relay-injection-events";
+import { RunnerQuotaPoller } from "./quota";
 import { capsFromEnv, contextStateDirFromEnv, logLevelFromEnv, mcpProxyEnabledFromEnv, orchestratorBaseDirFromEnv, orchestratorUrlFromEnv, registrationTimeoutMsFromEnv, runnerInfoFileFromEnv, runnerLogFileFromEnv, runnerOutboxDirWithInfoFallback, sessionDebugEnabled, tagsFromEnv, workspaceModeFromEnv } from "./config";
 import {
   appliedAgentProfileMetadata,
@@ -204,6 +205,7 @@ export class AgentRunner {
   private readonly sessionOutbox: Outbox;
   private readonly insights: RunnerInsights;
   private readonly busyReconciler: BusyReconciler;
+  private readonly quotaPoller: RunnerQuotaPoller;
   private currentToken?: string;
   private currentTokenJti?: string;
   private currentTokenProfileId?: string;
@@ -351,6 +353,7 @@ export class AgentRunner {
       clearProviderTurn: (reason) => this.forceClearProviderTurn(reason),
       sessionDebug: (message) => this.sessionDebug(message),
     });
+    this.quotaPoller = new RunnerQuotaPoller({ provider: options.provider, agentId: this.agentId, getProcess: () => this.process, onUpdate: () => this.publishStatus(), log: (message) => this.logRunnerDiagnostic(message) });
     this.bus = new RelayBusClient({
       url: relayBusUrl(options.relayUrl),
       role: "provider",
@@ -461,7 +464,7 @@ export class AgentRunner {
     void this.sweepStaleScratch();
     this.process = await this.spawnProvider();
     this.writeRunnerInfoFile();
-    this.processStartedAt = Date.now();
+    this.processStartedAt = Date.now(); this.quotaPoller.start();
     this.publishStatus();
     await this.deliverInitialPrompt();
     await this.bootstrapUnreadMessages();
@@ -493,7 +496,7 @@ export class AgentRunner {
     if (this.httpLivenessTimer) clearInterval(this.httpLivenessTimer);
     this.httpLivenessTimer = undefined;
     if (this.tokenRenewTimer) clearTimeout(this.tokenRenewTimer);
-    this.tokenRenewTimer = undefined;
+    this.tokenRenewTimer = undefined; this.quotaPoller.stop();
     this.busyReconciler.disarm();
     this.stopReasoningTail();
     this.obligationCache.stop();
@@ -934,6 +937,7 @@ export class AgentRunner {
       if (this.stopped) return;
       this.process = await this.spawnProvider();
       this.processStartedAt = Date.now();
+      this.quotaPoller.clear(); this.quotaPoller.start();
     } finally {
       this.restartInProgress = false;
     }
@@ -2110,21 +2114,19 @@ export class AgentRunner {
     const probeMetrics = this.latestProbeMetrics();
     const probeContext = probeMetrics ? contextStateFromProbeMetrics(probeMetrics) : undefined;
     const context = processContext ?? probeContext;
+    const quota = this.quotaPoller.current ?? (probeMetrics ? quotaStateFromProbeMetrics(probeMetrics) : undefined);
     const terminalSession = this.providerTerminalSession();
     const terminalSocket = this.providerTerminalSocket();
     const probeModel: ProbeModelInfo | undefined = probeMetrics?.model || probeMetrics?.effort
       ? { model: probeMetrics.model, effort: probeMetrics.effort }
       : undefined;
     const meta: Record<string, unknown> = {
-      providerCapabilities: runtimeProviderCapabilities(
-        this.options,
-        context,
-        probeModel,
-      ),
+      providerCapabilities: runtimeProviderCapabilities(this.options, context, probeModel, quota),
       ...(terminalSession ? { tmuxSession: terminalSession } : {}),
       ...(terminalSocket ? { tmuxSocket: terminalSocket } : {}),
     };
     if (context) meta.context = context;
+    if (quota) meta.quota = quota;
     return meta;
   }
 

package/src/runner-helpers.ts

@@ -1,5 +1,5 @@
 import { closeSync, openSync, readSync, statSync } from "node:fs";
-import type { AgentProfile, ContextState, Message, ProviderCapabilities } from "agent-relay-sdk";
+import type { AgentProfile, ContextState, Message, ProviderCapabilities, QuotaState } from "agent-relay-sdk";
 import { errMessage } from "agent-relay-sdk";
 import { targetMatchesAgentIdentity } from "agent-relay-sdk/agent-target";
 import type { ProviderAdapter, ProviderConfig, RunnerSpawnConfig, SemanticStatus } from "./adapter";
@@ -192,7 +192,7 @@ export function lifecycleCapabilities(): Record<string, true> {
   };
 }
 
-export function runtimeProviderCapabilities(options: RuntimeProviderOptions, contextState?: ContextState, probeModel?: ProbeModelInfo): ProviderCapabilities {
+export function runtimeProviderCapabilities(options: RuntimeProviderOptions, contextState?: ContextState, probeModel?: ProbeModelInfo, quotaState?: QuotaState): ProviderCapabilities {
   const model = options.model ?? probeModel?.model;
   const effort = options.effort ?? probeModel?.effort;
   const modelSource = options.model ? "runtime" as const : probeModel?.model ? "provider" as const : "runtime" as const;
@@ -225,6 +225,7 @@ export function runtimeProviderCapabilities(options: RuntimeProviderOptions, con
       lastUpdatedAt: options.startedAt,
     },
     ...runtimeProviderContextCapabilities(options, contextState),
+    ...runtimeProviderQuotaCapabilities(options, quotaState),
     ...runtimeProviderTerminalCapabilities(options),
     liveSession: {
       capture: true,
@@ -324,6 +325,25 @@ function runtimeProviderContextCapabilities(options: RuntimeProviderOptions, con
   return Object.keys(context).length ? { context } : {};
 }
 
+function runtimeProviderQuotaCapabilities(options: RuntimeProviderOptions, quotaState?: QuotaState): Pick<ProviderCapabilities, "quota"> {
+  if (options.provider !== "claude" && options.provider !== "codex") return {};
+  const fallbackWindows = options.provider === "claude"
+    ? [{ name: "five_hour", unit: "%" as const, reset: true }, { name: "seven_day", unit: "%" as const, reset: true }]
+    : [{ name: "primary", unit: "%" as const, reset: true }, { name: "secondary", unit: "%" as const, reset: true }];
+  return {
+    quota: {
+      supported: true,
+      source: quotaState?.source ?? "probe",
+      unit: quotaState?.windows[0]?.unit ?? "%",
+      windows: quotaState?.windows.map((window) => ({
+        name: window.name,
+        unit: window.unit,
+        reset: window.resetsAt !== undefined,
+      })) ?? fallbackWindows,
+    },
+  };
+}
+
 export function providerStateFromActiveWork(activeWork: Array<{ kind: string; metadata?: Record<string, unknown> }>): Record<string, unknown> | null {
   const providerTurn = activeWork.find((item) => item.kind === "provider-turn");
   const state = providerTurn?.metadata?.providerState;