agent-relay-runner 0.11.6 → 0.11.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.11.6",
+  "version": "0.11.9",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
     "directory": "runner"
   },
   "dependencies": {
-    "agent-relay-sdk": "0.2.4"
+    "agent-relay-sdk": "0.2.5"
   },
   "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.11.6",
+  "version": "0.11.9",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

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

@@ -82,3 +82,42 @@ relay_json_bool_field() {
 relay_json_escape() {
   printf '%s' "${1:-}" | sed 's/\\/\\\\/g; s/"/\\"/g'
 }
+
+# Print a short "request-review when done" reminder to stdout IFF this agent owns
+# an isolated workspace whose branch has committed work not yet integrated into
+# base. Prints nothing otherwise — so plain chat, shared-mode, and no-change
+# sessions never pay context/token cost. Reads the workspace from
+# AGENT_RELAY_WORKSPACE_JSON (set by the orchestrator at spawn) and does a local,
+# network-free git count. Always returns 0 (never aborts its caller).
+relay_review_reminder_text() {
+  local ws="${AGENT_RELAY_WORKSPACE_JSON:-}"
+  [ -z "$ws" ] && return 0
+  local mode worktree base id branch ahead
+  mode="$(relay_json_string_field mode "$ws")"
+  [ "$mode" = "isolated" ] || return 0
+  worktree="$(relay_json_string_field worktreePath "$ws")"
+  base="$(relay_json_string_field baseSha "$ws")"
+  [ -z "$base" ] && base="$(relay_json_string_field baseRef "$ws")"
+  id="$(relay_json_string_field id "$ws")"
+  branch="$(relay_json_string_field branch "$ws")"
+  [ -n "$worktree" ] || return 0
+  [ -n "$base" ] || return 0
+  [ -n "$id" ] || return 0
+  ahead="$(git -C "$worktree" rev-list --count "${base}..HEAD" 2>/dev/null || echo 0)"
+  case "$ahead" in ''|*[!0-9]*) ahead=0 ;; esac
+  [ "$ahead" -gt 0 ] || return 0
+  printf '[agent-relay] You have %s committed change(s) on `%s` that are not yet integrated into base. If your task is complete, request review so Agent Relay can auto-land it: POST /api/workspaces/%s/actions with {"action":"request-review"}. If you are still working, ignore this — it only appears while there is unmerged committed work.' \
+    "$ahead" "${branch:-this branch}" "$id"
+  return 0
+}
+
+# Wrap reminder text in the Claude Code additionalContext envelope for a given
+# hook event. Emits nothing when the text is empty.
+relay_emit_additional_context() {
+  local event="${1:-}" text="${2:-}"
+  [ -z "$event" ] && return 0
+  [ -z "$text" ] && return 0
+  printf '{"hookSpecificOutput":{"hookEventName":"%s","additionalContext":"%s"}}' \
+    "$event" "$(relay_json_escape "$text")"
+  return 0
+}

package/plugins/claude/hooks/session-start.sh

@@ -12,3 +12,9 @@ case "$source_kind" in
   *)
     ;;
 esac
+
+# Re-prime the request-review reminder when a session (re)starts — crucially on
+# source=="compact", which is how it survives a context compaction (PreCompact
+# cannot inject post-compact context; SessionStart can). No-op on a fresh startup
+# with no committed work, and silent for non-isolated/no-change sessions.
+relay_emit_additional_context SessionStart "$(relay_review_reminder_text || true)"

package/plugins/claude/hooks/user-prompt-submit.sh

@@ -2,3 +2,6 @@
 set -euo pipefail
 source "${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/hooks/relay-status.sh"
 relay_post_status busy
+# Re-surface the request-review reminder each turn while there is unmerged
+# committed work — so a long session can't "forget" to land it. Silent otherwise.
+relay_emit_additional_context UserPromptSubmit "$(relay_review_reminder_text || true)"

package/src/adapter.ts

@@ -12,6 +12,10 @@ export interface ProviderStatusEvent {
     status: string;
     id?: string;
     timestamp?: number;
+    title?: string;
+    body?: string;
+    icon?: string;
+    metadata?: Record<string, unknown>;
   };
   id?: string;
   label?: string;

package/src/runner.ts

@@ -1,5 +1,5 @@
 import { hostname } from "node:os";
-import { appendFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { appendFileSync, closeSync, mkdirSync, openSync, readSync, statSync, writeFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import type { AgentProfile, ContextState, Message, ProviderCapabilities, TaskStatusInput, WorkspaceMetadata } from "agent-relay-sdk";
@@ -67,6 +67,18 @@ const UNEXPECTED_EXIT_WINDOW_MS = 2 * 60 * 1000;
 const RAPID_EXIT_MS = 30 * 1000;
 const MAX_RAPID_UNEXPECTED_EXITS = 3;
 const MAX_TIMER_DELAY_MS = 2_147_483_647;
+const LOG_TAIL_BYTES = 128 * 1024;
+const CLAUDE_RESUME_RE = /\bclaude\s+--resume\s+([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\b/gi;
+
+interface RunnerTimelineEvent {
+  status: string;
+  id?: string;
+  timestamp: number;
+  title?: string;
+  body?: string;
+  icon?: string;
+  metadata?: Record<string, unknown>;
+}
 
 export class AgentRunner {
   private readonly agentId: string;
@@ -101,7 +113,7 @@ export class AgentRunner {
   private readonly unexpectedExitTimes: number[] = [];
   private readonly pendingMessages = new Map<number, Message>();
   private readonly activeTaskClaims = new Map<number, ActiveTaskClaim>();
-  private pendingTimelineEvent?: { status: string; id?: string; timestamp: number };
+  private pendingTimelineEvent?: RunnerTimelineEvent;
   private pendingPromptMessageId?: number;
   private scratch?: SessionScratchLayout;
 
@@ -579,9 +591,69 @@ export class AgentRunner {
       const recent = this.unexpectedExitTimes.filter((time) => now - time <= UNEXPECTED_EXIT_WINDOW_MS);
       recent.push(now);
       this.unexpectedExitTimes.splice(0, this.unexpectedExitTimes.length, ...recent);
+      const diagnostics = this.providerExitDiagnostics(status, runtimeMs);
+
+      this.publishRunnerTimelineEvent({
+        status: "provider.exit_detected",
+        id: `provider-exit-${this.providerSessionId}-${now}`,
+        timestamp: now,
+        title: "Provider exited",
+        body: `${this.options.provider} reported ${status} after ${Math.round(runtimeMs / 1000)}s`,
+        icon: "ti-plug-off",
+        metadata: {
+          eventType: "provider.exit_detected",
+          ...diagnostics,
+        },
+      });
+
+      if (this.shouldStopUnexpectedProviderExit(diagnostics)) {
+        const hasResumeId = typeof diagnostics.claudeResumeId === "string" && diagnostics.claudeResumeId.length > 0;
+        console.warn(`[runner] ${this.options.provider} exited; leaving agent offline for manual recovery`);
+        this.publishRunnerTimelineEvent({
+          status: "provider.restart_decision",
+          id: `provider-restart-decision-${this.providerSessionId}-${now}`,
+          timestamp: Date.now(),
+          title: "Provider restart skipped",
+          body: hasResumeId
+            ? "Claude exited; runner will not auto-resume. Resume id captured for manual recovery."
+            : "Claude exited; runner will not restart automatically.",
+          icon: "ti-player-stop",
+          metadata: {
+            eventType: "provider.restart_decision",
+            decision: "stop-surface",
+            reason: hasResumeId ? "claude-exit-manual-resume-available" : "claude-exit-manual-intervention-required",
+            ...diagnostics,
+          },
+        });
+        this.process = undefined;
+        this.setProviderStatus({
+          status,
+          reason: "provider-turn",
+          id: `provider-exit-${this.providerSessionId}`,
+          clear: ["provider-turn", "subagent"],
+        });
+        return;
+      }
 
       if (runtimeMs < RAPID_EXIT_MS && recent.length > MAX_RAPID_UNEXPECTED_EXITS) {
         console.error(`[runner] provider session exited ${recent.length} times within ${Math.round(UNEXPECTED_EXIT_WINDOW_MS / 1000)}s; giving up`);
+        this.publishRunnerTimelineEvent({
+          status: "provider.restart_decision",
+          id: `provider-restart-decision-${this.providerSessionId}-${now}`,
+          timestamp: Date.now(),
+          title: "Provider restart skipped",
+          body: `rapid unexpected exits exceeded ${MAX_RAPID_UNEXPECTED_EXITS}`,
+          icon: "ti-alert-triangle",
+          metadata: {
+            eventType: "provider.restart_decision",
+            decision: "give-up",
+            reason: "rapid-unexpected-provider-exits",
+            rapidExitCount: recent.length,
+            rapidExitWindowMs: UNEXPECTED_EXIT_WINDOW_MS,
+            maxRapidUnexpectedExits: MAX_RAPID_UNEXPECTED_EXITS,
+            ...diagnostics,
+          },
+        });
         this.setProviderStatus(status);
         this.options.onProviderExit?.(0);
         return;
@@ -589,6 +661,23 @@ export class AgentRunner {
 
       const delayMs = Math.min(10_000, Math.max(500, 500 * recent.length));
       console.warn(`[runner] provider session exited unexpectedly after ${Math.round(runtimeMs / 1000)}s; restarting in ${delayMs}ms`);
+      this.publishRunnerTimelineEvent({
+        status: "provider.restart_decision",
+        id: `provider-restart-decision-${this.providerSessionId}-${now}`,
+        timestamp: Date.now(),
+        title: "Provider restart scheduled",
+        body: `runner will start a fresh ${this.options.provider} provider in ${delayMs}ms`,
+        icon: "ti-refresh",
+        metadata: {
+          eventType: "provider.restart_decision",
+          decision: "restart-fresh",
+          reason: "unexpected-headless-terminal-exit",
+          delayMs,
+          rapidExitCount: recent.length,
+          rapidExitWindowMs: UNEXPECTED_EXIT_WINDOW_MS,
+          ...diagnostics,
+        },
+      });
       await Bun.sleep(delayMs);
       if (this.stopped || this.exitCommandInProgress) return;
       try {
@@ -605,6 +694,10 @@ export class AgentRunner {
     }
   }
 
+  private shouldStopUnexpectedProviderExit(diagnostics: Record<string, unknown>): boolean {
+    return this.options.provider === "claude" && diagnostics.exitCommandInProgress !== true;
+  }
+
   private async shutdownProvider(hard: boolean, timeoutMs = this.options.providerConfig.headless.shutdownTimeoutMs): Promise<void> {
     this.lifecycleAction = hard ? "killing" : "shutting-down";
     this.publishStatus();
@@ -620,6 +713,46 @@ export class AgentRunner {
     this.stopped = true;
   }
 
+  private publishRunnerTimelineEvent(event: RunnerTimelineEvent): void {
+    this.pendingTimelineEvent = {
+      ...event,
+      metadata: {
+        source: "runner",
+        provider: this.options.provider,
+        runnerId: this.options.runnerId,
+        agentId: this.agentId,
+        policyName: this.options.policyName ?? null,
+        spawnRequestId: this.options.spawnRequestId ?? null,
+        label: this.options.label ?? null,
+        providerSessionId: this.providerSessionId,
+        ...(event.metadata ?? {}),
+      },
+    };
+    this.publishStatus();
+  }
+
+  private providerExitDiagnostics(status: SemanticStatus, runtimeMs: number): Record<string, unknown> {
+    const tmuxSession = typeof this.process?.meta?.tmuxSession === "string" ? this.process.meta.tmuxSession : undefined;
+    const tmuxSocket = typeof this.process?.meta?.tmuxSocket === "string" ? this.process.meta.tmuxSocket : undefined;
+    const exitSource = tmuxSession ? "tmux-session-ended" : this.process?.process ? "process-exit" : "provider-status";
+    const logFile = typeof process.env.AGENT_RELAY_LOG_FILE === "string" ? process.env.AGENT_RELAY_LOG_FILE : undefined;
+    const claudeResumeId = this.options.provider === "claude" && logFile ? latestClaudeResumeIdFromLogFile(logFile) : undefined;
+    return {
+      status,
+      runtimeMs: Number.isFinite(runtimeMs) ? runtimeMs : null,
+      exitSource,
+      exitCommandInProgress: this.exitCommandInProgress,
+      stopped: this.stopped,
+      restartInProgress: this.restartInProgress,
+      restartPending: this.restartPending,
+      headless: this.options.headless,
+      hasTerminalSession: Boolean(tmuxSession),
+      tmuxSession: tmuxSession ?? null,
+      tmuxSocket: tmuxSocket ?? null,
+      claudeResumeId: claudeResumeId ?? null,
+    };
+  }
+
   private async updateCommand(commandId: string, status: string, result?: Record<string, unknown>, error?: string): Promise<void> {
     await this.bus.updateCommand(commandId, { status, ...(result ? { result } : {}), ...(error ? { error } : {}) });
   }
@@ -646,6 +779,10 @@ export class AgentRunner {
         status: update.timeline.status,
         ...(update.timeline.id ? { id: update.timeline.id } : {}),
         timestamp: update.timeline.timestamp ?? Date.now(),
+        ...(update.timeline.title ? { title: update.timeline.title } : {}),
+        ...(update.timeline.body ? { body: update.timeline.body } : {}),
+        ...(update.timeline.icon ? { icon: update.timeline.icon } : {}),
+        ...(update.timeline.metadata ? { metadata: update.timeline.metadata } : {}),
       };
     }
     if (status === "busy") {
@@ -874,9 +1011,20 @@ export class AgentRunner {
   private scheduleRuntimeTokenRenewal(delayMs?: number): void {
     if (this.tokenRenewTimer) clearTimeout(this.tokenRenewTimer);
     this.tokenRenewTimer = undefined;
-    if (!this.isRuntimeTokenRenewable()) return;
-    const computedDelay = delayMs ?? runtimeTokenRenewDelayMs(this.currentTokenExpiresAt!, Date.now());
-    if (computedDelay === undefined) return;
+    if (this.stopped) return;
+    const canSelfRenew = this.isRuntimeTokenRenewable();
+    const canRemint = this.canRemintViaOrchestrator();
+    // Keep the renewal clock ticking as long as the session can recover its token
+    // by EITHER path. Without the re-mint fallback an expired token would stop the
+    // timer forever (the old deadlock that stranded live agents off the bus).
+    if (!canSelfRenew && !canRemint) return;
+    let computedDelay = delayMs;
+    if (computedDelay === undefined) {
+      computedDelay = canSelfRenew
+        ? runtimeTokenRenewDelayMs(this.currentTokenExpiresAt!, Date.now())
+        : TOKEN_RENEW_RETRY_MS; // expired but re-mintable → retry via orchestrator soon
+      if (computedDelay === undefined) computedDelay = TOKEN_RENEW_RETRY_MS;
+    }
     const schedule = runtimeTokenRenewTimerSchedule(computedDelay);
     if (!schedule) return;
     this.tokenRenewTimer = setTimeout(() => {
@@ -889,6 +1037,8 @@ export class AgentRunner {
     }, schedule.delayMs);
   }
 
+  // Can the runner self-renew right now? Requires a non-expired runner-profile token
+  // (the relay rejects renewal of an expired token).
   private isRuntimeTokenRenewable(): boolean {
     return Boolean(
       this.currentToken &&
@@ -898,32 +1048,36 @@ export class AgentRunner {
     );
   }
 
+  // Can the runner recover its token via the orchestrator? Works even when the token
+  // is already expired — the orchestrator's standing credential is the authority.
+  private canRemintViaOrchestrator(): boolean {
+    return Boolean(
+      process.env.AGENT_RELAY_ORCHESTRATOR_URL &&
+      this.currentToken &&
+      (this.currentTokenProfileId === "provider-agent" || this.currentTokenProfileId === "provider-interactive"),
+    );
+  }
+
   private async renewRuntimeToken(): Promise<void> {
-    if (this.stopped || this.tokenRenewInFlight || !this.isRuntimeTokenRenewable()) return;
+    if (this.stopped || this.tokenRenewInFlight || !this.currentToken) return;
     this.tokenRenewInFlight = true;
     try {
-      const renewed = await this.http.renewRuntimeToken();
-      this.currentToken = renewed.token;
-      this.currentTokenJti = renewed.record.jti;
-      this.currentTokenProfileId = renewed.record.profileId ?? this.currentTokenProfileId;
-      this.currentTokenExpiresAt = renewed.record.expiresAt;
-      this.options.token = renewed.token;
-      this.options.tokenJti = renewed.record.jti;
-      this.options.tokenProfileId = this.currentTokenProfileId;
-      this.options.tokenExpiresAt = this.currentTokenExpiresAt;
-      this.http.setToken(renewed.token);
-      this.bus.setToken(renewed.token);
-      this.httpLivenessAuthFailed = false;
-      this.pendingTimelineEvent = {
-        status: "runtime-token-renewed",
-        id: renewed.record.jti,
-        timestamp: Date.now(),
-      };
-      this.bus.reconnectTransport("runtime token renewed");
-      this.publishStatus();
-      this.scheduleRuntimeTokenRenewal();
-    } catch (error) {
-      this.logRuntimeTokenRenewalFailure(error);
+      // Preferred path: self-renew directly against the relay while the token is
+      // still valid. Cheapest and needs no orchestrator round-trip.
+      if (this.isRuntimeTokenRenewable()) {
+        try {
+          const renewed = await this.http.renewRuntimeToken();
+          this.applyRenewedToken(renewed.token, renewed.record, "runtime-token-renewed");
+          return;
+        } catch (error) {
+          this.logRuntimeTokenRenewalFailure(error);
+          // Relay unreachable or token rejected — fall through to orchestrator re-mint.
+        }
+      }
+      // Recovery path: token expired, or self-renew failed. Ask the orchestrator —
+      // it holds a long-lived credential and can mint a fresh runner token, so a
+      // live session heals instead of being stranded off the bus.
+      if (this.canRemintViaOrchestrator() && await this.remintViaOrchestrator()) return;
       this.pendingTimelineEvent = {
         status: "runtime-token-renewal-failed",
         timestamp: Date.now(),
@@ -935,6 +1089,56 @@ export class AgentRunner {
     }
   }
 
+  // Apply a freshly issued token across every live surface — runner state, the
+  // RunnerOptions bag (re-injected into the provider on respawn), the HTTP client,
+  // the bus client — then force a bus handshake with the new token and reschedule.
+  private applyRenewedToken(
+    token: string,
+    record: { jti: string; profileId?: string; expiresAt?: number },
+    status: "runtime-token-renewed" | "runtime-token-reminted",
+  ): void {
+    this.currentToken = token;
+    this.currentTokenJti = record.jti;
+    this.currentTokenProfileId = record.profileId ?? this.currentTokenProfileId;
+    this.currentTokenExpiresAt = record.expiresAt;
+    this.options.token = token;
+    this.options.tokenJti = record.jti;
+    this.options.tokenProfileId = this.currentTokenProfileId;
+    this.options.tokenExpiresAt = this.currentTokenExpiresAt;
+    this.http.setToken(token);
+    this.bus.setToken(token);
+    this.httpLivenessAuthFailed = false;
+    this.pendingTimelineEvent = { status, id: record.jti, timestamp: Date.now() };
+    this.bus.reconnectTransport(status === "runtime-token-reminted" ? "runtime token re-minted" : "runtime token renewed");
+    this.publishStatus();
+    this.scheduleRuntimeTokenRenewal();
+  }
+
+  // Recover the runtime token through the orchestrator. The runner proxies its own
+  // (possibly expired) token; the orchestrator re-mints it via the relay using its
+  // standing credential. Returns true on success.
+  private async remintViaOrchestrator(): Promise<boolean> {
+    const orchUrl = process.env.AGENT_RELAY_ORCHESTRATOR_URL;
+    if (!orchUrl || !this.currentToken) return false;
+    try {
+      const res = await fetch(`${orchUrl.replace(/\/+$/, "")}/api/runtime-tokens/runner-renew`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ token: this.currentToken }),
+        signal: AbortSignal.timeout(10_000),
+      });
+      if (!res.ok) return false;
+      const renewed = await res.json() as { token?: string; record?: { jti: string; profileId?: string; expiresAt?: number } };
+      if (!renewed?.token || !renewed.record) return false;
+      this.applyRenewedToken(renewed.token, renewed.record, "runtime-token-reminted");
+      this.logRunnerDiagnostic(`[runner] runtime token re-minted via orchestrator (jti ${renewed.record.jti})`);
+      return true;
+    } catch (error) {
+      this.logRuntimeTokenRenewalFailure(error);
+      return false;
+    }
+  }
+
   private logRuntimeTokenRenewalFailure(error: unknown): void {
     const key = httpErrorKey(error);
     const now = Date.now();
@@ -1146,6 +1350,32 @@ export function runnerShouldRestartUnexpectedProviderExit(
     && input.hasTerminalSession;
 }
 
+export function latestClaudeResumeIdFromText(text: string): string | undefined {
+  let latest: string | undefined;
+  CLAUDE_RESUME_RE.lastIndex = 0;
+  for (let match = CLAUDE_RESUME_RE.exec(text); match; match = CLAUDE_RESUME_RE.exec(text)) {
+    latest = match[1];
+  }
+  return latest;
+}
+
+export function latestClaudeResumeIdFromLogFile(path: string): string | undefined {
+  let fd: number | undefined;
+  try {
+    const stat = statSync(path);
+    const length = Math.min(stat.size, LOG_TAIL_BYTES);
+    const offset = Math.max(0, stat.size - length);
+    const buffer = Buffer.alloc(length);
+    fd = openSync(path, "r");
+    readSync(fd, buffer, 0, length, offset);
+    return latestClaudeResumeIdFromText(buffer.toString("utf8"));
+  } catch {
+    return undefined;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
 function commandTimeoutMs(params: Record<string, unknown>, fallback = 10_000): number {
   const raw = params.timeoutMs;
   if (typeof raw !== "number" || !Number.isSafeInteger(raw) || raw <= 0) return fallback;