agent-relay-runner 0.73.1 → 0.75.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.73.1",
+  "version": "0.75.0",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
     "directory": "runner"
   },
   "dependencies": {
-    "agent-relay-sdk": "0.2.48"
+    "agent-relay-sdk": "0.2.50"
   },
   "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.73.1",
+  "version": "0.75.0",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/src/adapters/codex-agent-message-capture.ts

@@ -0,0 +1,56 @@
+type EmitAgentMessage = (body: string) => void;
+
+export class CodexAgentMessageCapture {
+  private segments: string[][] = [];
+  private currentSegment: string[] = [];
+  private readonly buffers = new Map<string, string>();
+  private readonly flushedLengths = new Map<string, number>();
+
+  reset(): void {
+    this.segments = [];
+    this.currentSegment = [];
+    this.buffers.clear();
+    this.flushedLengths.clear();
+  }
+
+  appendDelta(itemId: string | undefined, delta: string): void {
+    if (!itemId || !delta) return;
+    this.buffers.set(itemId, `${this.buffers.get(itemId) ?? ""}${delta}`);
+  }
+
+  completeItem(itemId: string | undefined, text: string | undefined, emit: EmitAgentMessage): void {
+    this.flushText(itemId, text ?? (itemId ? this.buffers.get(itemId) : undefined), emit);
+    if (!itemId) return;
+    this.buffers.delete(itemId);
+    this.flushedLengths.delete(itemId);
+  }
+
+  closeSegment(emit: EmitAgentMessage): void {
+    this.flushPending(emit);
+    if (!this.currentSegment.length) return;
+    this.segments.push(this.currentSegment);
+    this.currentSegment = [];
+  }
+
+  finish(emit: EmitAgentMessage): string | undefined {
+    this.closeSegment(emit);
+    const finalSegment = this.segments.at(-1);
+    this.segments = [];
+    return finalSegment?.length ? finalSegment.join("\n\n").trim() : undefined;
+  }
+
+  private flushPending(emit: EmitAgentMessage): void {
+    for (const [itemId, text] of [...this.buffers.entries()]) this.flushText(itemId, text, emit);
+  }
+
+  private flushText(itemId: string | undefined, text: string | undefined, emit: EmitAgentMessage): void {
+    if (!text) return;
+    const offset = itemId ? (this.flushedLengths.get(itemId) ?? 0) : 0;
+    const chunk = text.slice(offset);
+    if (itemId) this.flushedLengths.set(itemId, text.length);
+    const body = chunk.trim();
+    if (!body) return;
+    this.currentSegment.push(body);
+    emit(body);
+  }
+}

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/adapters/codex.ts

@@ -10,6 +10,7 @@ import { tomlString } from "../relay-mcp";
 import { assembleLaunch, bundledCodexSkillDirs, bundledSkillConfigArgs, materializeLaunchAssembly } from "../launch-assembly";
 import { logger } from "../logger";
 import type { SessionEvent } from "../session-insights";
+import { CodexAgentMessageCapture } from "./codex-agent-message-capture";
 
 /** Relay context prepended to a Codex agent's first turn: the standard relay
  * blurb plus, when running in an isolated workspace, the deps caveat (#159). */
@@ -49,12 +50,9 @@ export class CodexAdapter implements ProviderAdapter {
   // Active turn id for the main thread, captured from turn/started so an interrupt
   // can target the in-flight turn. Cleared on turn/completed.
   private activeTurnId?: string;
-  // Assistant message text accumulated across the current turn's agentMessage items,
-  // flushed as one session response on turn/completed (mirrors Claude's chatCaptureMode).
-  private turnMessages: string[] = [];
+  private readonly agentMessageCapture = new CodexAgentMessageCapture();
   private readonly itemTextBuffers = new Map<string, string>();
   private readonly itemTextBufferTypes = new Map<string, string>();
-  private captureMode: "final" | "full" = "final";
   // #183/#184: the normalized session-event log for the current process lifetime, fed
   // from the same completed-item stream that drives the chat mirror. The runner slices
   // this per-segment (since the last compact/clear/restart) via its own cursor, so we
@@ -81,7 +79,7 @@ export class CodexAdapter implements ProviderAdapter {
     this.subagentThreads.clear();
     this.pendingApprovals.clear();
     this.activeTurnId = undefined;
-    this.turnMessages = [];
+    this.agentMessageCapture.reset();
     this.itemTextBuffers.clear();
     this.itemTextBufferTypes.clear();
   }
@@ -133,7 +131,6 @@ export class CodexAdapter implements ProviderAdapter {
 
   async spawn(config: RunnerSpawnConfig): Promise<ManagedProcess> {
     this.resetProcessState();
-    this.captureMode = (config.providerConfig as ProviderConfig).chatCaptureMode ?? "final";
     const args = this.buildSpawnArgs(config, config.providerConfig as ProviderConfig);
     const appServer = Bun.spawn([args.command, ...args.args], {
       cwd: args.cwd,
@@ -459,8 +456,9 @@ export class CodexAdapter implements ProviderAdapter {
       } else {
         const turn = isRecord(params?.turn) ? params.turn : undefined;
         this.activeTurnId = stringValue(turn?.id);
-        this.turnMessages = [];
+        this.agentMessageCapture.reset();
         this.itemTextBuffers.clear();
+        this.itemTextBufferTypes.clear();
         this.statusCb({ status: "busy", reason: "provider-turn", id: this.activeTurnId });
       }
     }
@@ -492,29 +490,21 @@ export class CodexAdapter implements ProviderAdapter {
     }
   }
 
-  // Turn one completed Codex thread item into a session-mirror event. agentMessage
-  // text is accumulated and flushed as a single response on turn/completed; the rest
-  // (user prompt echo, reasoning, tool steps) is surfaced as it lands.
+  // Turn one completed Codex thread item into a session-mirror event. agentMessage text is
+  // mirrored as narration as it lands; only the final contiguous assistant segment is repeated
+  // as the turn-final response. The rest (user prompt echo, reasoning, tool steps) is surfaced
+  // as it lands.
   private handleCodexItem(item: Record<string, unknown> | undefined): void {
     if (!item) return;
     const type = stringValue(item.type);
     const turnId = this.activeTurnId;
     const itemId = codexItemId(item);
+    if (type !== "agentMessage") this.agentMessageCapture.closeSegment((body) => this.emitAgentNarration(body));
     // A completed non-reasoning item ends the reasoning segment that preceded it — flush the
     // buffered reasoning first so it lands in transcript order, ahead of this tool/message.
     if (type !== "reasoning") this.flushBufferedReasoning();
     if (type === "agentMessage") {
-      const text = (stringValue(item.text) ?? (itemId ? this.itemTextBuffers.get(itemId) : undefined))?.trim();
-      if (text) {
-        this.turnMessages.push(text);
-        this.recordInsightEvent({ type: "turn" }); // a substantive assistant turn
-        // Stream the assistant text into the trace as narration (Claude parity). The closing
-        // response bubble at turn end repeats the final block; the dashboard suppresses the
-        // matching narration so it isn't shown twice.
-        this.sessionEventCb({ type: "narration", origin: "provider", body: text, ...(turnId ? { turnId } : {}) });
-      }
-      if (itemId) this.itemTextBuffers.delete(itemId);
-      if (itemId) this.itemTextBufferTypes.delete(itemId);
+      this.agentMessageCapture.completeItem(itemId, stringValue(item.text), (body) => this.emitAgentNarration(body));
       return;
     }
     if (type === "userMessage") {
@@ -549,6 +539,14 @@ export class CodexAdapter implements ProviderAdapter {
     if (itemId) this.itemTextBufferTypes.delete(itemId);
   }
 
+  private emitAgentNarration(body: string): void {
+    this.recordInsightEvent({ type: "turn" }); // a substantive assistant turn
+    // Stream the assistant text into the trace as narration (Claude parity). The closing
+    // response bubble at turn end repeats the final block; the dashboard suppresses the
+    // matching narration so it isn't shown twice.
+    this.sessionEventCb({ type: "narration", origin: "provider", body, ...(this.activeTurnId ? { turnId: this.activeTurnId } : {}) });
+  }
+
   // Emit any buffered reasoning as discrete trace blocks (appended, in transcript order). Codex
   // streams reasoning as deltas with no reliable completion event, so we flush coarsely at item
   // and turn boundaries — the signal the Claude reasoning tail uses — never a codex-only timer.
@@ -588,6 +586,7 @@ export class CodexAdapter implements ProviderAdapter {
     const turnId = this.activeTurnId;
 
     if (method.includes("/started") || method.includes(".started")) {
+      if (type !== "agentMessage") this.agentMessageCapture.closeSegment((body) => this.emitAgentNarration(body));
       // A new item starting ends the prior reasoning segment — flush it ahead of this step.
       this.flushBufferedReasoning();
       const tool = codexToolSummary(type, item ?? params ?? {});
@@ -596,7 +595,14 @@ export class CodexAdapter implements ProviderAdapter {
       return;
     }
 
-    if (type === "agentMessage" || type === "reasoning" || type === "plan") {
+    if (type === "agentMessage") {
+      const delta = codexDeltaText(params);
+      if (delta) this.agentMessageCapture.appendDelta(itemId, delta);
+      return;
+    }
+
+    if (type === "reasoning" || type === "plan") {
+      this.agentMessageCapture.closeSegment((body) => this.emitAgentNarration(body));
       const delta = codexDeltaText(params);
       if (delta && itemId) {
         this.itemTextBuffers.set(itemId, `${this.itemTextBuffers.get(itemId) ?? ""}${delta}`);
@@ -611,15 +617,7 @@ export class CodexAdapter implements ProviderAdapter {
   }
 
   private flushTurnResponse(): void {
-    const pendingAgentMessages = [...this.itemTextBuffers.entries()]
-      .filter(([itemId]) => this.itemTextBufferTypes.get(itemId) === "agentMessage")
-      .map(([, text]) => text.trim())
-      .filter(Boolean);
-    const messages = [...this.turnMessages, ...pendingAgentMessages];
-    if (!messages.length) return;
-    const joined = this.captureMode === "full" ? messages.join("\n\n") : messages[messages.length - 1]!;
-    this.turnMessages = [];
-    const text = joined.trim();
+    const text = this.agentMessageCapture.finish((body) => this.emitAgentNarration(body));
     if (text) this.sessionEventCb({ type: "response", origin: "provider", body: text, final: true, ...(this.activeTurnId ? { turnId: this.activeTurnId } : {}) });
   }
 
@@ -631,6 +629,7 @@ export class CodexAdapter implements ProviderAdapter {
     this.pendingApprovals.clear();
     this.itemTextBuffers.clear();
     this.itemTextBufferTypes.clear();
+    this.agentMessageCapture.reset();
     this.statusCb({ status: "idle", reason: "provider-turn", id: turnId });
   }
 

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;