agent-relay-runner 0.31.1 → 0.32.2

package/package.json

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

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

@@ -44,9 +44,16 @@ relay_post_session_turn() {
   local last_assistant_message="${2:-}"
   local port="${AGENT_RELAY_RUNNER_PORT:-}"
   [ -z "$port" ] && return 0
-  [ -z "$transcript_path" ] && return 0
-  local body="{\"transcriptPath\":\"$(relay_json_escape "$transcript_path")\""
-  [ -n "$last_assistant_message" ] && body="${body},\"lastAssistantMessage\":${last_assistant_message}"
+  # transcript_path is the primary capture source, but the Stop payload can omit it
+  # (known CC edge case). last_assistant_message is the fallback for exactly that —
+  # POST with whichever we have; only bail when both are missing.
+  [ -z "$transcript_path" ] && [ -z "$last_assistant_message" ] && return 0
+  local body="{"
+  [ -n "$transcript_path" ] && body="${body}\"transcriptPath\":\"$(relay_json_escape "$transcript_path")\""
+  if [ -n "$last_assistant_message" ]; then
+    [ "$body" != "{" ] && body="${body},"
+    body="${body}\"lastAssistantMessage\":${last_assistant_message}"
+  fi
   body="${body}}"
   curl -fsS -X POST "http://127.0.0.1:${port}/session-turn" \
     -H 'Content-Type: application/json' \

package/src/control-server.ts

@@ -352,8 +352,13 @@ async function handleSessionTurn(req: Request, options: ControlServerOptions): P
   if (!options.onSessionTurn) return Response.json({ ok: false, reason: "session capture unavailable" });
   const body = await req.json().catch(() => null);
   const transcriptPath = isRecord(body) && typeof body.transcriptPath === "string" ? body.transcriptPath : "";
-  if (!transcriptPath) return Response.json({ ok: false, reason: "transcriptPath required" }, { status: 400 });
   const lastAssistantMessage = isRecord(body) ? body.lastAssistantMessage : undefined;
+  // transcriptPath is the primary source, but it can be absent (known CC Stop edge case).
+  // lastAssistantMessage is the fallback for exactly that — accept either; reject only when
+  // both are missing so the turn still reaches the dashboard chat (#264).
+  if (!transcriptPath && lastAssistantMessage === undefined) {
+    return Response.json({ ok: false, reason: "transcriptPath or lastAssistantMessage required" }, { status: 400 });
+  }
   // Awaited on purpose: the Stop hook posts this synchronously before its
   // reply-obligation check, so the captured turn must be persisted (and the
   // obligation cleared) before this response returns.

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; });