agent-relay-runner 0.32.1 → 0.32.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.32.1",
+  "version": "0.32.3",
   "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.32.1",
+  "version": "0.32.3",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/src/outbox.ts

@@ -68,6 +68,10 @@ const DEFAULTS = {
   pollMs: 5_000,
 };
 
+// Pause between forced delivery attempts during flush() — keeps a brief server outage
+// from hot-looping while still retrying fast enough to land within the flush deadline.
+const FLUSH_RETRY_PAUSE_MS = 150;
+
 interface Row {
   seq: number;
   kind: string;
@@ -93,6 +97,8 @@ export class Outbox {
 
   private draining = false;
   private rerun = false;
+  // Set by flush() to make the next drain pass ignore per-row backoff (deliver NOW).
+  private forceDue = false;
   private pollTimer?: ReturnType<typeof setInterval>;
   private dueTimer?: ReturnType<typeof setTimeout>;
   private stopped = false;
@@ -185,24 +191,45 @@ export class Outbox {
     this.pollTimer.unref?.();
   }
 
+  // Drain everything we can before the process exits, ignoring per-row backoff. Used on
+  // shutdown/kill/crash (#183): the capture seam durably enqueues the end-of-session
+  // Insights datapoint, but the per-agent outbox is never reopened once the agent is gone,
+  // so a row that hasn't been POSTed yet is stranded forever. flush() blocks (bounded) on
+  // delivery — the opposite intent of the polite, backoff-respecting steady-state drain.
+  // Returns true if the queue fully drained within the deadline.
+  async flush(timeoutMs: number): Promise<boolean> {
+    const deadline = Date.now() + Math.max(0, timeoutMs);
+    for (;;) {
+      if (this.stopped) return this.pendingCount() === 0;
+      if (this.pendingCount() === 0) return true;
+      await this.drain(true);
+      if (this.pendingCount() === 0) return true;
+      if (Date.now() >= deadline) return false;
+      await new Promise<void>((resolve) => setTimeout(resolve, FLUSH_RETRY_PAUSE_MS));
+    }
+  }
+
   // Process the queue strictly oldest-first. Coalesces concurrent calls; if a drain is
   // requested while one is running, it re-runs once at the end (so an enqueue during a
-  // send isn't missed).
-  async drain(): Promise<void> {
+  // send isn't missed). `force` (from flush) makes this pass ignore per-row backoff.
+  async drain(force = false): Promise<void> {
     if (this.stopped) return;
+    if (force) this.forceDue = true;
     if (this.draining) { this.rerun = true; return; }
     this.draining = true;
     try {
       do {
         this.rerun = false;
-        await this.drainOnce();
-      } while (this.rerun && !this.stopped);
+        const due = this.forceDue;
+        this.forceDue = false;
+        await this.drainOnce(due);
+      } while ((this.rerun || this.forceDue) && !this.stopped);
     } finally {
       this.draining = false;
     }
   }
 
-  private async drainOnce(): Promise<void> {
+  private async drainOnce(force = false): Promise<void> {
     for (;;) {
       if (this.stopped) return;
       const row = this.db
@@ -211,7 +238,7 @@ export class Outbox {
       if (!row) return;
 
       const now = Date.now();
-      if (row.next_attempt_at > now) {
+      if (!force && row.next_attempt_at > now) {
         // Head isn't due yet. Don't reorder past it (FIFO) — schedule a wake-up and stop.
         this.scheduleDue(row.next_attempt_at - now);
         return;

package/src/runner.ts

@@ -26,7 +26,15 @@ import { ensureSessionScratch, reapSessionScratch, sweepStaleSessions, type Sess
 // capture, #183/#184) before the invasive operation and, during that window, presents a
 // distinct non-addressable lifecycle state. Bus commands and provider hooks (Claude
 // PreCompact / SessionEnd) both normalize to one of these.
-type SessionDestroyReason = "compact" | "clear" | "restart" | "shutdown" | "kill";
+type SessionDestroyReason = "compact" | "clear" | "restart" | "shutdown" | "kill" | "crash";
+
+// Reasons after which the runner process won't survive to drain the durable outbox (and the
+// per-agent outbox is never reopened once the agent is gone). For these, pre-destroy must
+// block on delivery of the just-captured Insights datapoint, not just enqueue it (#183).
+// `restart` (bus command) deliberately excluded: the runner stays alive and drains normally.
+function reasonExitsRunner(reason: SessionDestroyReason): boolean {
+  return reason === "shutdown" || reason === "kill" || reason === "crash";
+}
 
 // `finalizing-<reason>` is the transient pre-destroy window; the others are the executing
 // teardown states the dashboard already renders.
@@ -38,6 +46,11 @@ type LifecycleAction =
 // transcript read or a wedged provider from stalling a shutdown the operator asked for.
 const PRE_DESTROY_TIMEOUT_MS = 4_000;
 
+// Bounded window to deliver the durable outbox before an exit-bound teardown (#183). Kept
+// short so a wedged/down server can't stall an operator-requested shutdown for long; a
+// row that still can't land is logged, not silently dropped.
+const OUTBOX_FLUSH_TIMEOUT_MS = 3_000;
+
 // Map a lifecycle bus command to its destructive boundary reason, or undefined for
 // non-destructive commands (interrupt, inject, reconnect, permission decisions).
 function boundaryReasonForCommand(type: string): SessionDestroyReason | undefined {
@@ -815,6 +828,16 @@ export class AgentRunner {
     if (this.restartPending) return;
     this.restartPending = true;
     try {
+      // Best-effort Insights capture for the segment that just ended in a crash (#183). This
+      // path has no controlled teardown, so without it crashed sessions silently drop their
+      // context-ratio datapoint. The process handle is still set (cleared later), so the
+      // Claude transcript is readable; the runner stays alive here (restart or offline), so the
+      // durable outbox drains normally — no flush needed.
+      await Promise.race([
+        this.captureContextRatio("crash"),
+        new Promise<void>((resolve) => setTimeout(resolve, PRE_DESTROY_TIMEOUT_MS)),
+      ]).catch((error) => this.sessionLog(`insights: crash capture failed: ${errMessage(error)}`));
+
       const now = Date.now();
       const runtimeMs = this.processStartedAt ? now - this.processStartedAt : Number.POSITIVE_INFINITY;
       const recent = this.unexpectedExitTimes.filter((time) => now - time <= UNEXPECTED_EXIT_WINDOW_MS);
@@ -1308,6 +1331,17 @@ export class AgentRunner {
       } catch (error) {
         this.sessionLog(`insights: pre-destroy capture failed: ${errMessage(error)}`);
       }
+      // For exit-bound transitions the runner won't be alive afterward to drain the durable
+      // outbox, so block (bounded) on delivering what capture just enqueued. This runs before
+      // handleCommand's finally deletes the agent, so the runtime token is still valid here.
+      if (reasonExitsRunner(reason)) {
+        try {
+          const delivered = await this.outbox.flush(OUTBOX_FLUSH_TIMEOUT_MS);
+          if (!delivered) this.sessionLog(`insights: outbox flush incomplete before ${reason} (${this.outbox.pendingCount()} pending)`);
+        } catch (error) {
+          this.sessionLog(`insights: outbox flush failed: ${errMessage(error)}`);
+        }
+      }
     })();
     this.preDestroyPromise = run;
     void run.finally(() => { this.preDestroyPromise = undefined; });