agent-relay-runner 0.106.0 → 0.107.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.106.0",
+  "version": "0.107.0",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {
@@ -21,7 +21,7 @@
   },
   "dependencies": {
     "agent-relay-providers": "0.104.0",
-    "agent-relay-sdk": "0.2.92",
+    "agent-relay-sdk": "0.2.93",
     "callmux": "0.23.0"
   },
   "devDependencies": {

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

package/src/adapters/claude-status-detectors.ts

@@ -0,0 +1,147 @@
+import { extractClaudeModelUnavailableMessage } from "agent-relay-sdk";
+import type { ProviderStatusUpdate } from "../adapter";
+import { buildRateLimitProviderState, parseClaudeRateLimitPane } from "../rate-limit";
+
+// LEGACY PANE-SCRAPE FALLBACK (#766/#768) — busy/idle is now driven primarily by
+// Claude Code's intrinsic session probe (readClaudeSessionStatus, ./claude-session-probe):
+// `$CLAUDE_CONFIG_DIR/sessions/<pid>.json` carries a machine-readable `status` field
+// on CC ≥2.1.119. These two pane heuristics are the SOLE fallback for pre-2.1.119 /
+// probe-missing sessions, and claudePaneLooksReady still backs the input-readiness gate
+// (waitForClaudeInputReady) + the prompt-gate busy guard — so they stay. They string-match
+// CC's TUI chrome against captured tmux scrollback (~80 lines), so they break whenever CC
+// restyles its footer/banner. Deliberately substring/regex based (no machine-readable
+// signal existed when these were written). Known break conditions, so the next CC restyle
+// is a fast fix rather than a hunt:
+//   readiness (claudePaneLooksReady) breaks if CC renames/removes ALL of: the
+//     "bypass permissions" / "shift+tab to cycle" / "? for shortcuts" footer hints,
+//     the "/effort" hint, or the "Welcome back" / "Claude Code" banner.
+//   busy (claudePaneIsBusy) breaks if CC drops the live "… (<elapsed>" spinner counter
+//     (the cross-version anchor; the "esc to interrupt" hint was already dropped in 2.1.x).
+//   FALSE POSITIVES: agent output that literally QUOTES any of these strings (e.g. a
+//     transcript discussing "esc to interrupt", or this very comment shown in a pane)
+//     reads as ready/busy. Tolerated because the markers are CC-specific enough to be
+//     rare in real output; if it bites, gate on the LAST N lines only (the live footer).
+// History: 18067b5 (busy counter), and the readiness footer-vs-banner fix below.
+export function claudePaneLooksReady(text: string): boolean {
+  // Claude's startup banner ("Claude Code" / "Welcome back") scrolls off the pane once the
+  // conversation fills it, so a mid-session delivery (e.g. the budget warning, minutes into
+  // a run) must detect readiness from the PERSISTENT input-box footer that Claude always
+  // renders at the prompt. Requiring the banner made every delivery after the first screen
+  // of output time out as "input not ready". Any one of these strong, Claude-specific
+  // markers means the TUI is up and the input box exists.
+  return text.includes("bypass permissions")   // footer in --dangerously-skip-permissions mode
+    || text.includes("shift+tab to cycle")       // mode-cycle footer hint (persistent)
+    || text.includes("? for shortcuts")          // default footer hint (persistent)
+    || text.includes("/effort")
+    || text.includes("Welcome back")
+    || text.includes("Claude Code");
+}
+
+// The working-spinner footer carries a live elapsed-time counter while a turn is in
+// flight, e.g. "✶ Perambulating… (2m 17s · ↓ 8.7k tokens)" — gerund, "… (", then
+// "[Nh ][Nm ]Ns". Anchored on the gerund ellipsis so it can't match the "… +N lines
+// (ctrl+o to expand)" truncation marker, the idle input box, or the persistent
+// "/btw … without interrupting Claude's current work" queue hint.
+const CLAUDE_BUSY_SPINNER_RE = /…\s*\((?:\d+h\s+)?(?:\d+m\s+)?\d+s\b/;
+
+export function claudePaneIsBusy(text: string): boolean {
+  // Claude Code <2.1.x rendered "(esc to interrupt)" in the spinner footer; 2.1.x
+  // dropped that hint but kept the "(<elapsed>" counter, which is the stable busy
+  // signal across versions. Match either so the busy probe (and the reconciler
+  // backstop that depends on it) keep working as the footer wording changes.
+  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: parsed.errorType ?? "session_limit", kind: parsed.kind ?? "usage_limit",
+      ...(parsed.resetAt ? { resetAt: parsed.resetAt } : {}),
+      message: parsed.message,
+      source: sessionName ? `claude-pane:${sessionName}` : "claude-pane",
+    }),
+  };
+}
+
+// #769 — detect the API connection-retry banner in the live terminal footer and surface a
+// transient blocked hold (non-terminal, clears on recovery). Three stable anchors from the
+// banner text: "Unable to connect to API", "Retrying in <N>s", "attempt <N>/<M>".
+// Gated on the LAST N lines so agent output that merely QUOTES these strings (e.g. quoting
+// this comment, or a discussion of retry logic) doesn't false-positive — the live banner
+// always lives in the footer; quoted strings appear in the scrollback body.
+// Break condition: if CC renames/removes any anchor substring the detector stops firing and
+// sessions return to idle/available — a fast fix once the new footer wording is known.
+const CLAUDE_CONN_RETRY_FOOTER_LINES = 10;
+const CLAUDE_CONN_RETRY_ANCHOR_RE = /Unable to connect to API/;
+const CLAUDE_CONN_RETRY_RATE_RE = /Retrying in \d+s/;
+const CLAUDE_CONN_RETRY_ATTEMPT_RE = /attempt \d+\/\d+/;
+
+export function claudeConnectionRetryStatus(text: string, sessionName?: string): ProviderStatusUpdate | null {
+  const footer = text.split("\n").slice(-CLAUDE_CONN_RETRY_FOOTER_LINES).join("\n");
+  if (
+    !CLAUDE_CONN_RETRY_ANCHOR_RE.test(footer) ||
+    !CLAUDE_CONN_RETRY_RATE_RE.test(footer) ||
+    !CLAUDE_CONN_RETRY_ATTEMPT_RE.test(footer)
+  ) return null;
+  const now = Date.now();
+  return {
+    status: "idle",
+    clear: ["subagent"],
+    providerState: {
+      state: "blocked",
+      reason: "conn_retry",
+      kind: "conn_retry",
+      label: "connection degraded · retrying",
+      message: "Claude cannot reach the Anthropic API and is retrying the connection.",
+      source: sessionName ? `claude-pane:${sessionName}` : "claude-pane",
+      terminal: false,
+      recommendedAction: "Holding; agent-relay will clear this state once the session reconnects.",
+      enteredAt: now,
+      updatedAt: now,
+    },
+  };
+}
+
+export function claudeModelUnavailableStatus(text: string, sessionName?: string): ProviderStatusUpdate | null {
+  const message = extractClaudeModelUnavailableMessage(text);
+  if (!message) return null;
+  return {
+    status: "error",
+    clear: ["provider-turn", "subagent"],
+    providerState: {
+      state: "failed",
+      reason: "model-unavailable",
+      message,
+      source: "claude-pane",
+      terminal: true,
+      ...(sessionName ? { sessionName } : {}),
+      recommendedAction: "Choose a different Claude model before restarting this agent.",
+    },
+    metadata: {
+      terminalFailureReason: "model-unavailable",
+      terminalFailureMessage: message,
+    },
+    timeline: {
+      status: "provider.restart_decision",
+      id: `provider-model-unavailable-${Date.now()}`,
+      timestamp: Date.now(),
+      title: "Provider restart skipped",
+      body: message,
+      icon: "ti-player-stop",
+      metadata: {
+        eventType: "provider.restart_decision",
+        decision: "stop-surface",
+        reason: "model-unavailable",
+        modelUnavailable: true,
+        modelUnavailableMessage: message,
+      },
+    },
+  };
+}

package/src/adapters/claude.ts

@@ -2,7 +2,7 @@ import { chmodSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
 import { join, resolve } from "node:path";
-import { extractClaudeModelUnavailableMessage, type Message } from "agent-relay-sdk";
+import { type Message } from "agent-relay-sdk";
 import { shellEscape as shellQuote } from "agent-relay-sdk/shell-utils";
 import { tmuxCommand, tmuxHasSession } from "agent-relay-sdk/tmux-utils";
 import { sanitizeFsName } from "agent-relay-sdk/fs-name";
@@ -15,8 +15,8 @@ import { prepareClaudeProfileHome, profileUsesClaudeHostProviderGlobals } from "
 import { assembleLaunch, materializeLaunchAssembly, sessionStatusLineSettingsArgs } from "../launch-assembly";
 import { claudeProviderMessageText } from "./claude-delivery";
 import { claudeProbeActivity, readManagedClaudeStatus, resolveClaudePid, type ClaudeProbeActivity } from "./claude-session-probe";
-import { buildRateLimitProviderState, parseClaudeRateLimitPane } from "../rate-limit";
 import { evaluateClaudePromptGatePane, initialClaudePromptGatePaneState, type ClaudePromptGatePaneState } from "../claude-prompt-gates";
+import { claudePaneLooksReady, claudePaneIsBusy, claudeRateLimitStatus, claudeConnectionRetryStatus, claudeModelUnavailableStatus } from "./claude-status-detectors";
 
 export class ClaudeAdapter implements ProviderAdapter {
   readonly provider = "claude";
@@ -28,6 +28,7 @@ export class ClaudeAdapter implements ProviderAdapter {
   private tmuxWatcher?: Timer;
   private turnWatcher?: Timer;
   private modelUnavailableReported = false;
+  private connectionRetryActive = false;
   private promptGatePaneState: ClaudePromptGatePaneState = initialClaudePromptGatePaneState();
 
   onStatusChange(cb: (status: ProviderStatusUpdate) => void): void {
@@ -347,6 +348,7 @@ export class ClaudeAdapter implements ProviderAdapter {
   private async spawnHeadless(config: RunnerSpawnConfig, spawnArgs: SpawnArgs): Promise<ManagedProcess> {
     const { sessionName, socketName, args: tmuxArgs } = this.buildTmuxArgs(config, spawnArgs);
     this.modelUnavailableReported = false;
+    this.connectionRetryActive = false;
     this.promptGatePaneState = initialClaudePromptGatePaneState();
 
     Bun.spawnSync(tmuxCommand(socketName, "kill-session", "-t", sessionName), {
@@ -409,6 +411,18 @@ export class ClaudeAdapter implements ProviderAdapter {
         this.statusCb(status);
         return;
       }
+      // #769: connection-retry banner detection. Emits a transient blocked hold while the
+      // pane shows the retry footer; clears to idle when the banner disappears (API recovered).
+      const connRetryStatus = claudeConnectionRetryStatus(pane, sessionName);
+      if (connRetryStatus) {
+        if (!this.connectionRetryActive) {
+          this.connectionRetryActive = true;
+          this.statusCb(connRetryStatus);
+        }
+      } else if (this.connectionRetryActive) {
+        this.connectionRetryActive = false;
+        this.statusCb("idle");
+      }
       // #663: prompt-gate fallback. Known gates should be prevented before launch;
       // this catches missed/new blocking panes with the same #655 debounce + busy
       // guard used for rate-limit holds.
@@ -540,110 +554,9 @@ function captureTmuxPane(sessionName: string, socketName?: string): string {
   return result.stdout.toString();
 }
 
-// LEGACY PANE-SCRAPE FALLBACK (#766/#768) — busy/idle is now driven primarily by
-// Claude Code's intrinsic session probe (readClaudeSessionStatus, ./claude-session-probe):
-// `$CLAUDE_CONFIG_DIR/sessions/<pid>.json` carries a machine-readable `status` field
-// on CC ≥2.1.119. These two pane heuristics are the SOLE fallback for pre-2.1.119 /
-// probe-missing sessions, and claudePaneLooksReady still backs the input-readiness gate
-// (waitForClaudeInputReady) + the prompt-gate busy guard — so they stay. They string-match
-// CC's TUI chrome against captured tmux scrollback (~80 lines), so they break whenever CC
-// restyles its footer/banner. Deliberately substring/regex based (no machine-readable
-// signal existed when these were written). Known break conditions, so the next CC restyle
-// is a fast fix rather than a hunt:
-//   readiness (claudePaneLooksReady) breaks if CC renames/removes ALL of: the
-//     "bypass permissions" / "shift+tab to cycle" / "? for shortcuts" footer hints,
-//     the "/effort" hint, or the "Welcome back" / "Claude Code" banner.
-//   busy (claudePaneIsBusy) breaks if CC drops the live "… (<elapsed>" spinner counter
-//     (the cross-version anchor; the "esc to interrupt" hint was already dropped in 2.1.x).
-//   FALSE POSITIVES: agent output that literally QUOTES any of these strings (e.g. a
-//     transcript discussing "esc to interrupt", or this very comment shown in a pane)
-//     reads as ready/busy. Tolerated because the markers are CC-specific enough to be
-//     rare in real output; if it bites, gate on the LAST N lines only (the live footer).
-// History: 18067b5 (busy counter), and the readiness footer-vs-banner fix below.
-export function claudePaneLooksReady(text: string): boolean {
-  // Claude's startup banner ("Claude Code" / "Welcome back") scrolls off the pane once the
-  // conversation fills it, so a mid-session delivery (e.g. the budget warning, minutes into
-  // a run) must detect readiness from the PERSISTENT input-box footer that Claude always
-  // renders at the prompt. Requiring the banner made every delivery after the first screen
-  // of output time out as "input not ready". Any one of these strong, Claude-specific
-  // markers means the TUI is up and the input box exists.
-  return text.includes("bypass permissions")   // footer in --dangerously-skip-permissions mode
-    || text.includes("shift+tab to cycle")       // mode-cycle footer hint (persistent)
-    || text.includes("? for shortcuts")          // default footer hint (persistent)
-    || text.includes("/effort")
-    || text.includes("Welcome back")
-    || text.includes("Claude Code");
-}
-
-// The working-spinner footer carries a live elapsed-time counter while a turn is in
-// flight, e.g. "✶ Perambulating… (2m 17s · ↓ 8.7k tokens)" — gerund, "… (", then
-// "[Nh ][Nm ]Ns". Anchored on the gerund ellipsis so it can't match the "… +N lines
-// (ctrl+o to expand)" truncation marker, the idle input box, or the persistent
-// "/btw … without interrupting Claude's current work" queue hint.
-const CLAUDE_BUSY_SPINNER_RE = /…\s*\((?:\d+h\s+)?(?:\d+m\s+)?\d+s\b/;
-
-export function claudePaneIsBusy(text: string): boolean {
-  // Claude Code <2.1.x rendered "(esc to interrupt)" in the spinner footer; 2.1.x
-  // dropped that hint but kept the "(<elapsed>" counter, which is the stable busy
-  // signal across versions. Match either so the busy probe (and the reconciler
-  // backstop that depends on it) keep working as the footer wording changes.
-  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: parsed.errorType ?? "session_limit", kind: parsed.kind ?? "usage_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;
-  return {
-    status: "error",
-    clear: ["provider-turn", "subagent"],
-    providerState: {
-      state: "failed",
-      reason: "model-unavailable",
-      message,
-      source: "claude-pane",
-      terminal: true,
-      ...(sessionName ? { sessionName } : {}),
-      recommendedAction: "Choose a different Claude model before restarting this agent.",
-    },
-    metadata: {
-      terminalFailureReason: "model-unavailable",
-      terminalFailureMessage: message,
-    },
-    timeline: {
-      status: "provider.restart_decision",
-      id: `provider-model-unavailable-${Date.now()}`,
-      timestamp: Date.now(),
-      title: "Provider restart skipped",
-      body: message,
-      icon: "ti-player-stop",
-      metadata: {
-        eventType: "provider.restart_decision",
-        decision: "stop-surface",
-        reason: "model-unavailable",
-        modelUnavailable: true,
-        modelUnavailableMessage: message,
-      },
-    },
-  };
-}
+// Re-export pane-status detectors (moved to ./claude-status-detectors) so existing
+// import paths (including claude.test.ts) continue to resolve via this module.
+export { claudePaneLooksReady, claudePaneIsBusy, claudeRateLimitStatus, claudeConnectionRetryStatus, claudeModelUnavailableStatus } from "./claude-status-detectors";
 
 async function waitForClaudeInputReady(sessionName: string, timeoutMs = CLAUDE_TMUX_READY_TIMEOUT_MS, socketName?: string): Promise<void> {
   const deadline = Date.now() + timeoutMs;