agent-relay-runner 0.54.0 → 0.56.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.54.0",
+  "version": "0.56.0",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {

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.54.0",
+  "version": "0.56.0",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/plugins/claude/hooks/relay-status.sh

@@ -31,6 +31,26 @@ relay_post_status_clearing_subagents() {
   relay_post_status "$1" "${2:-}" "${3:-}" "${4:-}" "${5:-}" "${6:-}" subagent
 }
 
+# Report a provider usage/rate-limit hold to the runner (#286). The runner turns
+# this into a `providerState: blocked` (reason rate_limit), posts a chat notice,
+# and auto-resumes the agent once the window resets. reset_time (unix seconds,
+# only "if available" per CC StopFailure docs) drives the resume; the runner falls
+# back to a poll window when it is absent. Fire-and-forget like the other reports.
+relay_post_rate_limit() {
+  local error_type="${1:-}"
+  local reset_time="${2:-}"
+  local error_message="${3:-}"
+  local port="${AGENT_RELAY_RUNNER_PORT:-}"
+  [ -z "$port" ] && return 0
+  local body="{\"errorType\":\"$(relay_json_escape "$error_type")\""
+  case "$reset_time" in ''|*[!0-9]*) ;; *) body="${body},\"resetTime\":${reset_time}" ;; esac
+  [ -n "$error_message" ] && body="${body},\"errorMessage\":\"$(relay_json_escape "$error_message")\""
+  body="${body}}"
+  curl -fsS -X POST "http://127.0.0.1:${port}/rate-limit" \
+    -H 'Content-Type: application/json' \
+    -d "$body" >/dev/null 2>&1 || true
+}
+
 relay_post_timeline_status() {
   relay_post_status "$1" "${2:-provider-turn}" "" "" "" "" "${3:-}" "$4"
 }
@@ -146,6 +166,13 @@ relay_json_string_field() {
   printf '%s' "$input" | sed -nE 's/.*"'"$field"'"[[:space:]]*:[[:space:]]*"([^"]*)".*/\1/p' | head -1
 }
 
+relay_json_number_field() {
+  local field="${1:-}"
+  local input="${2:-}"
+  [ -z "$field" ] && return 0
+  printf '%s' "$input" | sed -nE 's/.*"'"$field"'"[[:space:]]*:[[:space:]]*([0-9]+).*/\1/p' | head -1
+}
+
 relay_json_bool_field() {
   local field="${1:-}"
   local input="${2:-}"

package/plugins/claude/hooks/stop-failure.sh

@@ -4,10 +4,28 @@ source "${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/
 relay_install_hook_guard stop-failure
 
 payload="$(cat || true)"
-error="$(relay_json_string_field error "$payload")"
+# CC sends the error class as `error_type` (StopFailure docs, verified 2026-06);
+# fall back to legacy `error` so older payloads / tests still match.
+error="$(relay_json_string_field error_type "$payload")"
+[ -z "$error" ] && error="$(relay_json_string_field error "$payload")"
+reset_time="$(relay_json_number_field reset_time "$payload")"
+error_message="$(relay_json_string_field error_message "$payload")"
 
+# #286: a usage/rate-limit stall is transient and time-bounded — hold the agent
+# (providerState blocked) and auto-resume at reset, instead of silently going idle.
+# The disambiguator for billing_error is reset_time: a subscription rolling-window
+# limit carries one (and is auto-resumable); true credit exhaustion does not (fatal).
 case "$error" in
-  authentication_failed|oauth_org_not_allowed|billing_error|model_not_found)
+  rate_limit|overloaded)
+    relay_post_rate_limit "$error" "$reset_time" "$error_message"
+    ;;
+  billing_error)
+    case "$reset_time" in
+      ''|*[!0-9]*) relay_post_status_clearing_subagents error ;;
+      *) relay_post_rate_limit "$error" "$reset_time" "$error_message" ;;
+    esac
+    ;;
+  authentication_failed|oauth_org_not_allowed|model_not_found)
     relay_post_status_clearing_subagents error
     ;;
   *)

package/src/adapters/claude.ts

@@ -12,6 +12,7 @@ import type { SessionEvent } from "../session-insights";
 import { prepareClaudeProfileHome, profileUsesHostProviderGlobals } from "../profile-home";
 import { relayMcpClaudeConfigArg } from "../relay-mcp";
 import { claudeProviderMessageText } from "./claude-delivery";
+import { buildRateLimitProviderState, parseClaudeRateLimitPane } from "../rate-limit";
 
 export class ClaudeAdapter implements ProviderAdapter {
   readonly provider = "claude";
@@ -23,6 +24,9 @@ export class ClaudeAdapter implements ProviderAdapter {
   private tmuxWatcher?: Timer;
   private turnWatcher?: Timer;
   private modelUnavailableReported = false;
+  // #286: true while a usage-limit modal is being held, so the pane watcher dismisses
+  // it + emits the hold once (not every 2s tick). Cleared when the modal leaves the pane.
+  private rateLimitReported = false;
 
   onStatusChange(cb: (status: ProviderStatusUpdate) => void): void {
     this.statusCb = cb;
@@ -358,10 +362,36 @@ export class ClaudeAdapter implements ProviderAdapter {
       if (status) {
         this.modelUnavailableReported = true;
         this.statusCb(status);
+        return;
+      }
+      // #286: the subscription usage-limit modal fires no hook, so detect it from the
+      // pane. Dismiss it (Escape = "wait", which just stops the turn) so the agent
+      // returns to a clean prompt the resume `continue` can land on, then hold it.
+      const rateLimit = claudeRateLimitStatus(pane, sessionName);
+      if (rateLimit) {
+        if (!this.rateLimitReported) {
+          this.rateLimitReported = true;
+          this.dismissRateLimitModal(sessionName, socketName);
+          this.statusCb(rateLimit);
+        }
+      } else if (this.rateLimitReported) {
+        // Modal gone (dismissed, or a real turn resumed) — re-arm for the next limit.
+        this.rateLimitReported = false;
       }
     }, 2000);
   }
 
+  // Send Escape to dismiss the usage-limit modal — the "wait" choice, which stops the
+  // turn (per the CC TUI) and returns the agent to a normal idle prompt. Best-effort:
+  // a failed send-keys must never wedge the pane watcher.
+  private dismissRateLimitModal(sessionName: string, socketName?: string): void {
+    try {
+      Bun.spawnSync(tmuxCommand(socketName, "send-keys", "-t", sessionName, "Escape"), { stdin: "ignore", stdout: "ignore", stderr: "ignore" });
+    } catch {
+      // ignore — the hold still publishes; worst case the modal lingers until the next tick.
+    }
+  }
+
   private async shutdownTmux(sessionName: string, opts: { graceful: boolean; timeoutMs: number }, socketName?: string): Promise<void> {
     this.stopTurnWatch();
     if (this.tmuxWatcher) {
@@ -531,6 +561,24 @@ export function claudePaneIsBusy(text: string): boolean {
   return CLAUDE_BUSY_SPINNER_RE.test(text) || text.includes("esc to interrupt");
 }
 
+// #286: detect the subscription usage-limit modal in the pane and turn it into the
+// provider-neutral rate-limit hold (idle + blocked) that the relay's resume sweep lifts
+// at reset. Mirrors claudeModelUnavailableStatus, but non-terminal (idle, not error).
+export function claudeRateLimitStatus(text: string, sessionName?: string): ProviderStatusUpdate | null {
+  const parsed = parseClaudeRateLimitPane(text);
+  if (!parsed) return null;
+  return {
+    status: "idle",
+    clear: ["subagent"],
+    providerState: buildRateLimitProviderState({
+      errorType: "session_limit",
+      ...(parsed.resetAt ? { resetAt: parsed.resetAt } : {}),
+      message: parsed.message,
+      source: sessionName ? `claude-pane:${sessionName}` : "claude-pane",
+    }),
+  };
+}
+
 export function claudeModelUnavailableStatus(text: string, sessionName?: string): ProviderStatusUpdate | null {
   const message = extractClaudeModelUnavailableMessage(text);
   if (!message) return null;

package/src/control-server.ts

@@ -3,6 +3,7 @@ import type { Message, ReplyObligation } from "agent-relay-sdk";
 import { errMessage, isRecord } from "agent-relay-sdk";
 import type { ProviderPermissionDecisionInput, ProviderStatusEvent, SemanticStatus, TerminalAttachSpec } from "./adapter";
 import { logger, parseLogLevel, LOG_LEVELS } from "./logger";
+import { buildRateLimitProviderState } from "./rate-limit";
 
 // A hook that failed in a way it could not handle itself reports here so the
 // failure is never silent (#198 item 5). Phase 1 logs it FATAL to the per-agent
@@ -106,6 +107,9 @@ export function startControlServer(options: ControlServerOptions): ControlServer
       if (url.pathname === "/hook-fatal" && req.method === "POST") {
         return handleHookFatal(req, options);
       }
+      if (url.pathname === "/rate-limit" && req.method === "POST") {
+        return handleRateLimit(req, options);
+      }
       if (url.pathname === "/monitor") {
         const upgraded = srv.upgrade(req, { data: { kind: "monitor" } });
         return upgraded ? undefined : new Response("WebSocket upgrade failed", { status: 400 });
@@ -441,6 +445,28 @@ async function handleStatus(req: Request, options: ControlServerOptions): Promis
   return Response.json({ ok: true, ...update });
 }
 
+// #286: the stop-failure hook reports a usage/rate-limit stall here. Build the
+// provider-neutral `blocked` state (reason rate_limit) — the same seam Claude
+// model-unavailable and Codex approvals ride — so the dashboard shows it
+// distinctly (never as idle/available) and the relay's resume sweep can lift it
+// at reset. The agent stays `idle` underneath (the turn truly ended); the runner
+// carries the hold via its rateLimitHold field, not an active-work claim.
+async function handleRateLimit(req: Request, options: ControlServerOptions): Promise<Response> {
+  const body = await req.json().catch(() => null);
+  if (!isRecord(body)) return Response.json({ error: "invalid body" }, { status: 400 });
+  const errorType = typeof body.errorType === "string" && body.errorType ? body.errorType : "rate_limit";
+  // CC's reset_time is unix SECONDS ("if available"); normalize to ms for the relay.
+  const resetTimeSec = typeof body.resetTime === "number" && Number.isFinite(body.resetTime) ? body.resetTime : undefined;
+  const resetAt = resetTimeSec !== undefined ? Math.round(resetTimeSec * 1000) : undefined;
+  const errorMessage = typeof body.errorMessage === "string" && body.errorMessage ? body.errorMessage : undefined;
+  options.onStatus({
+    status: "idle",
+    clear: ["subagent"],
+    providerState: buildRateLimitProviderState({ errorType, resetAt, message: errorMessage, source: "claude" }),
+  });
+  return Response.json({ ok: true, errorType, ...(resetAt ? { resetAt } : {}) });
+}
+
 function statusTimelineEvent(body: Partial<ProviderStatusEvent> | null): ProviderStatusEvent["timeline"] | undefined {
   const timeline = body?.timeline;
   if (!timeline || typeof timeline !== "object" || Array.isArray(timeline)) return undefined;

package/src/rate-limit.ts

@@ -0,0 +1,156 @@
+// #286 — shared rate-limit hold construction + Claude pane detection.
+//
+// Two detection arms feed the SAME provider-neutral `blocked` hold:
+//   1. The StopFailure hook (clean API-error turn-end: API-429/auth/billing) → control-server.
+//   2. Pane-scrape of the subscription "session/weekly limit" modal (no hook exists for it —
+//      anthropics/claude-code#34817 was closed not-planned) → the Claude adapter.
+// Both build the hold here so the shape stays identical, and the relay's resume sweep
+// (services/rate-limit-resume.ts) lifts either once the window resets.
+
+export const RATE_LIMIT_BLOCK_REASON = "rate_limit";
+
+// Reject a parsed reset that's in the past or implausibly far out — a bad parse would
+// otherwise resume too early (thrash) or hold for days. Beyond this we drop resetAt and
+// fall back to the resume sweep's poll window.
+const MAX_RESET_AHEAD_MS = 7 * 24 * 60 * 60 * 1000;
+
+export interface RateLimitHoldInput {
+  errorType?: string;
+  /** Unix ms the limit window resets, when known. */
+  resetAt?: number;
+  message?: string;
+  source?: string;
+}
+
+/** The blocked providerState a rate-limit hold carries. Shared by both detection arms. */
+export function buildRateLimitProviderState(input: RateLimitHoldInput): Record<string, unknown> {
+  const now = Date.now();
+  const resetAt = typeof input.resetAt === "number" && Number.isFinite(input.resetAt) ? input.resetAt : undefined;
+  const label = resetAt ? `usage limit · resets ${formatResetClock(resetAt)}` : "usage limit reached";
+  return {
+    state: "blocked",
+    reason: RATE_LIMIT_BLOCK_REASON,
+    label,
+    recommendedAction: "Holding until the usage window resets; agent-relay auto-resumes the agent.",
+    source: input.source ?? "claude",
+    errorType: input.errorType ?? RATE_LIMIT_BLOCK_REASON,
+    enteredAt: now,
+    ...(resetAt ? { resetAt } : {}),
+    ...(input.message ? { message: input.message } : {}),
+    updatedAt: now,
+  };
+}
+
+/** Host-local HH:MM for the chat notice / badge label (matches how the CLI shows "resets 3:45pm"). */
+function formatResetClock(resetAtMs: number): string {
+  try {
+    return new Date(resetAtMs).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
+  } catch {
+    return new Date(resetAtMs).toISOString().slice(11, 16);
+  }
+}
+
+// The subscription limit line wordings seen in the wild (claude-auto-retry patterns +
+// claude-auto-retry#15: "session"/"weekly limit" slipped past older regexes). We REQUIRE a
+// limit phrase AND a reset/retry phrase on the same line so normal output mentioning
+// "rate limit" can't false-positive the hold.
+const LIMIT_PHRASE_RE = /(?:hit (?:your|the)\s*(?:[\w-]+\s+)*limit|usage limit|\d+-hour limit|limit reached|out of (?:extra )?usage|rate limit(?:\s+(?:hit|reached|exceeded))?|weekly limit|session limit)/i;
+const RESET_AT_RE = /\bresets?\b(?:\s+at)?\s+(\d{1,2})(?::(\d{2}))?\s*(am|pm)?\s*(?:\(([^)]+)\))?/i;
+const TRY_AGAIN_RE = /\btry again in\s+(\d+)\s*(second|minute|hour|day)s?/i;
+
+export interface PaneRateLimit {
+  /** The matched limit line, for the chat notice / observability. */
+  message: string;
+  /** Unix ms reset, when parseable from the pane (else undefined → resume falls back to poll). */
+  resetAt?: number;
+}
+
+/**
+ * Detect a Claude usage/rate-limit modal in a captured tmux pane and parse its reset time.
+ * Requires BOTH a limit phrase and a reset/retry phrase (anywhere in the pane, so it's robust
+ * to a modal that wraps the two onto separate lines) — that pairing is what distinguishes the
+ * real modal from normal output mentioning "rate limit". Returns null otherwise. `nowMs` is
+ * injectable for tests.
+ */
+export function parseClaudeRateLimitPane(text: string, nowMs: number = Date.now()): PaneRateLimit | null {
+  if (!text) return null;
+  const limit = LIMIT_PHRASE_RE.exec(text);
+  if (!limit) return null;
+  const message = limitLineAt(text, limit.index);
+
+  const relative = TRY_AGAIN_RE.exec(text);
+  if (relative) {
+    const unitMs = { second: 1000, minute: 60_000, hour: 3_600_000, day: 86_400_000 }[relative[2]!.toLowerCase()] ?? 0;
+    const resetAt = clampReset(nowMs + Number(relative[1]) * unitMs, nowMs);
+    return { message, ...(resetAt ? { resetAt } : {}) };
+  }
+  const reset = RESET_AT_RE.exec(text);
+  if (reset) {
+    const resetAt = clampReset(parseClockReset(reset, nowMs), nowMs);
+    return { message, ...(resetAt ? { resetAt } : {}) };
+  }
+  // Limit phrase but no reset/retry anywhere — not confident it's the modal; skip to
+  // avoid false-positiving on normal output (docs, the agent's own text) that says "limit".
+  return null;
+}
+
+// The clean limit line containing the match offset, stripped of box-drawing chrome.
+function limitLineAt(text: string, index: number): string {
+  const start = text.lastIndexOf("\n", index) + 1;
+  const endNl = text.indexOf("\n", index);
+  const end = endNl === -1 ? text.length : endNl;
+  return text.slice(start, end).replace(/[│┌┐└┘─┤├╭╮╯╰]/g, " ").replace(/\s+/g, " ").trim();
+}
+
+function clampReset(resetAt: number | undefined, nowMs: number): number | undefined {
+  if (resetAt === undefined || !Number.isFinite(resetAt)) return undefined;
+  if (resetAt <= nowMs || resetAt - nowMs > MAX_RESET_AHEAD_MS) return undefined;
+  return resetAt;
+}
+
+// Next occurrence of a wall-clock "H[:MM] am/pm" in the message's IANA timezone (if given
+// and valid) or host-local. Timezone-aware so "resets 4:50pm (Asia/Shanghai)" is correct
+// regardless of where the runner host sits.
+function parseClockReset(match: RegExpExecArray, nowMs: number): number | undefined {
+  let hour = Number(match[1]);
+  const minute = match[2] ? Number(match[2]) : 0;
+  const meridiem = match[3]?.toLowerCase();
+  const tz = match[4]?.trim();
+  if (!Number.isFinite(hour) || hour > 23 || minute > 59) return undefined;
+  if (meridiem === "pm" && hour < 12) hour += 12;
+  if (meridiem === "am" && hour === 12) hour = 0;
+
+  if (tz && isValidTimeZone(tz)) {
+    const { y, mo, d, offsetMs } = tzWallAndOffset(tz, nowMs);
+    let target = Date.UTC(y, mo - 1, d, hour, minute, 0) - offsetMs;
+    if (target <= nowMs) target += 86_400_000;
+    return target;
+  }
+  const d = new Date(nowMs);
+  d.setHours(hour, minute, 0, 0);
+  let target = d.getTime();
+  if (target <= nowMs) target += 86_400_000;
+  return target;
+}
+
+function isValidTimeZone(tz: string): boolean {
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: tz });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// The target TZ's wall-clock date and UTC offset at `atMs`, via Intl (no deps).
+function tzWallAndOffset(tz: string, atMs: number): { y: number; mo: number; d: number; offsetMs: number } {
+  const dtf = new Intl.DateTimeFormat("en-US", {
+    timeZone: tz, hour12: false,
+    year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit", second: "2-digit",
+  });
+  const parts = Object.fromEntries(dtf.formatToParts(new Date(atMs)).map((p) => [p.type, p.value])) as Record<string, string>;
+  const y = Number(parts.year), mo = Number(parts.month), d = Number(parts.day);
+  const h = Number(parts.hour) % 24, mi = Number(parts.minute), s = Number(parts.second);
+  const asUtc = Date.UTC(y, mo - 1, d, h, mi, s);
+  return { y, mo, d, offsetMs: asUtc - atMs };
+}

package/src/runner.ts

@@ -278,6 +278,12 @@ export class AgentRunner {
   // busy reconciler doesn't mistake a permission prompt for a stuck-busy turn.
   private providerBlocked = false;
   private terminalFailure?: { reason: string; message: string; providerState?: Record<string, unknown> };
+  // #286: a usage/rate-limit hold. The turn truly ended (idle), but the agent is
+  // held until the limit resets, so this can't ride an active-work claim like the
+  // permission-blocked state does. publishStatus surfaces it as the agent's
+  // providerState; it clears when a new turn starts (the relay's resume message
+  // wakes one) so the blocked badge lifts on its own.
+  private rateLimitHold?: Record<string, unknown>;
   // Reasoning tailer (item 5): streams the in-flight turn's reasoning/tool steps
   // from the Claude transcript into chat as discreet session events.
   private reasoningTail?: { timer: ReturnType<typeof setInterval>; seen: Set<string> };
@@ -1103,11 +1109,22 @@ export class AgentRunner {
       };
     }
     if (typeof update !== "string" && update.providerState) {
-      const state = (update.providerState as { state?: unknown }).state;
-      this.providerBlocked = state === "blocked";
+      const ps = update.providerState as { state?: unknown; reason?: unknown };
+      this.providerBlocked = ps.state === "blocked";
+      // A rate-limit hold persists across the idle the turn ends on; any other
+      // providerState supersedes it (clears a stale hold).
+      if (ps.state === "blocked" && ps.reason === "rate_limit") {
+        const fresh = !this.rateLimitHold;
+        this.rateLimitHold = update.providerState;
+        if (fresh) this.publishRateLimitNotice(update.providerState);
+      } else {
+        this.rateLimitHold = undefined;
+      }
     } else if (status === "idle") {
       this.providerBlocked = false;
     }
+    // Forward progress (a real turn) lifts the hold so the blocked badge clears.
+    if (status === "busy") this.rateLimitHold = undefined;
     if (typeof update !== "string" && status === "error") {
       const terminalReason = typeof update.metadata?.terminalFailureReason === "string"
         ? update.metadata.terminalFailureReason
@@ -1780,6 +1797,21 @@ export class AgentRunner {
     });
   }
 
+  // #286: a discreet, durable chat marker when a usage/rate-limit hold begins, via
+  // the same session-mirror lane as the compaction notice. Outbound session event
+  // (NOT an inbound message) so it shows in the dashboard chat WITHOUT waking a turn
+  // — waking a still-limited agent would just re-fail. The relay sends the waking
+  // resume message later, once the window has reset.
+  private publishRateLimitNotice(providerState: Record<string, unknown>): void {
+    const label = typeof providerState.label === "string" && providerState.label ? providerState.label : "usage limit reached";
+    this.publishSessionEvent({
+      from: this.agentId,
+      to: "user",
+      body: `⏳ ${label} — holding; agent-relay will auto-resume at reset.`,
+      session: { type: "notice", origin: "provider", label: "rate-limit", ...(this.currentTurnId ? { turnId: this.currentTurnId } : {}) },
+    });
+  }
+
   private publishStatus(): void {
     this.claims.expire();
     const status = this.claims.currentStatus();
@@ -1787,7 +1819,7 @@ export class AgentRunner {
     const activeWork = this.claims.activeWork();
     const activeSubagents = activeWork.filter((item) => item.kind === "subagent");
     const terminalFailure = this.terminalFailure;
-    const providerState = terminalFailure?.providerState ?? providerStateFromActiveWork(activeWork);
+    const providerState = terminalFailure?.providerState ?? this.rateLimitHold ?? providerStateFromActiveWork(activeWork);
     this.bus.setSemanticStatus(status === "offline" || status === "error" ? "idle" : status);
     const timelineEvent = this.pendingTimelineEvent;
     this.pendingTimelineEvent = undefined;