agent-relay-runner 0.38.0 → 0.40.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
     "directory": "runner"
   },
   "dependencies": {
-    "agent-relay-sdk": "0.2.23"
+    "agent-relay-sdk": "0.2.25"
   },
   "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.38.0",
+  "version": "0.40.0",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/src/adapter.ts

@@ -36,13 +36,17 @@ export type ProviderStatusUpdate = SemanticStatus | ProviderStatusEvent;
  * same lane Claude's transcript capture uses. Provider-independent boundary.
  */
 export interface ProviderSessionEvent {
-  type: "prompt" | "response" | "reasoning" | "tool";
+  type: "prompt" | "response" | "narration" | "reasoning" | "tool";
   body: string;
   origin?: "chat" | "terminal" | "provider";
   turnId?: string;
   label?: string;
   status?: "running" | "completed" | "failed";
   streaming?: boolean;
+  /** Stable provider-side step id (Codex app-server item id). Carried into
+   * MessageSessionMeta.stepId so the server upserts the step's row in place instead of
+   * appending a duplicate (a tool's running→completed, a streamed reasoning row). */
+  stepId?: string;
 }
 
 export interface ProviderConfig {

package/src/adapters/claude.ts

@@ -2,7 +2,7 @@ import { 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 type { Message } from "agent-relay-sdk";
+import { extractClaudeModelUnavailableMessage, 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";
@@ -21,6 +21,7 @@ export class ClaudeAdapter implements ProviderAdapter {
   private statusCb: (status: ProviderStatusUpdate) => void = () => {};
   private tmuxWatcher?: Timer;
   private turnWatcher?: Timer;
+  private modelUnavailableReported = false;
 
   onStatusChange(cb: (status: ProviderStatusUpdate) => void): void {
     this.statusCb = cb;
@@ -285,6 +286,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;
 
     Bun.spawnSync(tmuxCommand(socketName, "kill-session", "-t", sessionName), {
       stdin: "ignore", stdout: "ignore", stderr: "ignore",
@@ -332,6 +334,19 @@ export class ClaudeAdapter implements ProviderAdapter {
         clearInterval(this.tmuxWatcher!);
         this.tmuxWatcher = undefined;
         this.statusCb("offline");
+        return;
+      }
+      if (this.modelUnavailableReported) return;
+      let pane = "";
+      try {
+        pane = captureTmuxPane(sessionName, socketName);
+      } catch {
+        return;
+      }
+      const status = claudeModelUnavailableStatus(pane, sessionName);
+      if (status) {
+        this.modelUnavailableReported = true;
+        this.statusCb(status);
       }
     }, 2000);
   }
@@ -505,6 +520,43 @@ export function claudePaneIsBusy(text: string): boolean {
   return CLAUDE_BUSY_SPINNER_RE.test(text) || text.includes("esc to interrupt");
 }
 
+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,
+      },
+    },
+  };
+}
+
 async function waitForClaudeInputReady(sessionName: string, timeoutMs = CLAUDE_TMUX_READY_TIMEOUT_MS, socketName?: string): Promise<void> {
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {

package/src/adapters/codex.ts

@@ -476,11 +476,18 @@ export class CodexAdapter implements ProviderAdapter {
     const type = stringValue(item.type);
     const turnId = this.activeTurnId;
     const itemId = codexItemId(item);
+    // A completed non-reasoning item ends the reasoning segment that preceded it — flush the
+    // buffered reasoning first so it lands in transcript order, ahead of this tool/message.
+    if (type !== "reasoning") this.flushBufferedReasoning();
     if (type === "agentMessage") {
       const text = (stringValue(item.text) ?? (itemId ? this.itemTextBuffers.get(itemId) : undefined))?.trim();
       if (text) {
         this.turnMessages.push(text);
         this.recordInsightEvent({ type: "turn" }); // a substantive assistant turn
+        // Stream the assistant text into the trace as narration (Claude parity). The closing
+        // response bubble at turn end repeats the final block; the dashboard suppresses the
+        // matching narration so it isn't shown twice.
+        this.sessionEventCb({ type: "narration", origin: "provider", body: text, ...(turnId ? { turnId } : {}) });
       }
       if (itemId) this.itemTextBuffers.delete(itemId);
       if (itemId) this.itemTextBufferTypes.delete(itemId);
@@ -495,23 +502,43 @@ export class CodexAdapter implements ProviderAdapter {
       return;
     }
     if (type === "reasoning") {
-      const buffered = itemId ? this.itemTextBuffers.get(itemId) : undefined;
-      const text = (codexReasoningText(item) || buffered || "").trim();
-      if (text) this.sessionEventCb({ type: "reasoning", origin: "provider", body: text, ...(turnId ? { turnId } : {}) });
-      if (itemId) this.itemTextBuffers.delete(itemId);
-      if (itemId) this.itemTextBufferTypes.delete(itemId);
+      // Codex has no reliable reasoning item/completed carrying text — the stream IS the deltas.
+      // Keep the longer of (accumulated deltas, item.content) in the buffer and emit at the next
+      // boundary (next item / turn end), the same coarse signal the Claude reasoning tail uses.
+      const fromItem = codexReasoningText(item);
+      if (itemId && fromItem) {
+        const existing = this.itemTextBuffers.get(itemId) ?? "";
+        if (fromItem.length >= existing.length) this.itemTextBuffers.set(itemId, fromItem);
+        this.itemTextBufferTypes.set(itemId, "reasoning");
+      }
       return;
     }
     const tool = codexToolSummary(type, item);
     if (tool) {
       this.recordInsightEvent({ type: "tool", name: codexInsightToolName(type, item) });
       if (codexItemFailed(item)) this.recordInsightEvent({ type: "tool_error" });
-      this.sessionEventCb({ type: "tool", origin: "provider", body: tool.body, label: tool.label, status: "completed", ...(turnId ? { turnId } : {}) });
+      // stepId = the app-server item id: the server upserts the running step emitted on
+      // item/started into this completed state IN PLACE, so the tool persists as ONE row.
+      this.sessionEventCb({ type: "tool", origin: "provider", body: tool.body, label: tool.label, status: "completed", ...(turnId ? { turnId } : {}), ...(itemId ? { stepId: itemId } : {}) });
     }
     if (itemId) this.itemTextBuffers.delete(itemId);
     if (itemId) this.itemTextBufferTypes.delete(itemId);
   }
 
+  // Emit any buffered reasoning as discrete trace blocks (appended, in transcript order). Codex
+  // streams reasoning as deltas with no reliable completion event, so we flush coarsely at item
+  // and turn boundaries — the signal the Claude reasoning tail uses — never a codex-only timer.
+  private flushBufferedReasoning(): void {
+    const turnId = this.activeTurnId;
+    for (const [itemId, text] of [...this.itemTextBuffers.entries()]) {
+      if (this.itemTextBufferTypes.get(itemId) !== "reasoning") continue;
+      this.itemTextBuffers.delete(itemId);
+      this.itemTextBufferTypes.delete(itemId);
+      const body = text.trim();
+      if (body) this.sessionEventCb({ type: "reasoning", origin: "provider", body, ...(turnId ? { turnId } : {}) });
+    }
+  }
+
   // #183/#184: append to the session-event log with a soft cap. On overflow we drop the
   // oldest half; the runner detects the resulting length shrink and resets its segment
   // cursor (worst case: one slightly-truncated datapoint on a pathologically long session).
@@ -537,8 +564,11 @@ export class CodexAdapter implements ProviderAdapter {
     const turnId = this.activeTurnId;
 
     if (method.includes("/started") || method.includes(".started")) {
+      // A new item starting ends the prior reasoning segment — flush it ahead of this step.
+      this.flushBufferedReasoning();
       const tool = codexToolSummary(type, item ?? params ?? {});
-      if (tool) this.sessionEventCb({ type: "tool", origin: "provider", body: tool.body, label: tool.label, status: "running", streaming: true, ...(turnId ? { turnId } : {}) });
+      // stepId = item id so the server upserts this running step → completed IN PLACE (one row).
+      if (tool) this.sessionEventCb({ type: "tool", origin: "provider", body: tool.body, label: tool.label, status: "running", streaming: true, ...(turnId ? { turnId } : {}), ...(itemId ? { stepId: itemId } : {}) });
       return;
     }
 
@@ -570,6 +600,7 @@ export class CodexAdapter implements ProviderAdapter {
   }
 
   private finishMainTurn(): void {
+    this.flushBufferedReasoning(); // surface any trailing reasoning before the closing response
     this.flushTurnResponse();
     const turnId = this.activeTurnId;
     this.activeTurnId = undefined;

package/src/runner.ts

@@ -251,6 +251,12 @@ export class AgentRunner {
   // its final response. Set when a provider-turn starts, cleared when it ends.
   private currentTurnId?: string;
   private currentTurnStartedAt?: number;
+  // True while a turn that was already in flight is being compacted. Claude's PostCompact
+  // hook posts a single `idle`, but a mid-turn compaction RESUMES the turn afterward — so
+  // treating that idle as a turn end (flip idle, kill the reasoning tail) makes chat go dark
+  // until the next prompt. Set when `compacting` arrives with a turn running; cleared on the
+  // genuine end (a plain idle with no compaction timeline).
+  private compactionMidTurn = false;
   // Prompt-echo dedup: a short, time-bounded queue of prompts the runner itself
   // injected (chat box or initial prompt) that are still awaiting their matching
   // UserPromptSubmit echo. A single slot dropped earlier entries when several prompts
@@ -269,6 +275,7 @@ export class AgentRunner {
   // Tracks whether the provider is in a legitimate blocked/approval state, so the
   // 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> };
   // 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> };
@@ -1092,10 +1099,47 @@ export class AgentRunner {
     } else if (status === "idle") {
       this.providerBlocked = false;
     }
+    if (typeof update !== "string" && status === "error") {
+      const terminalReason = typeof update.metadata?.terminalFailureReason === "string"
+        ? update.metadata.terminalFailureReason
+        : typeof update.providerState?.reason === "string"
+          ? update.providerState.reason
+          : "provider-error";
+      const terminalMessage = typeof update.metadata?.terminalFailureMessage === "string"
+        ? update.metadata.terminalFailureMessage
+        : typeof update.providerState?.message === "string"
+          ? update.providerState.message
+          : "Provider reported an unrecoverable error.";
+      this.terminalFailure = {
+        reason: terminalReason,
+        message: terminalMessage,
+        ...(update.providerState ? { providerState: update.providerState } : {}),
+      };
+    } else if (status === "idle" || status === "busy") {
+      this.terminalFailure = undefined;
+    }
+    // Compaction lifecycle (Claude PreCompact→`compacting` busy / PostCompact→`compacted`
+    // idle). A `compacted` idle for a turn that predated compaction is a hook artifact — the
+    // turn resumes — so it must NOT end the turn. Discriminate on whether a turn was running,
+    // captured BEFORE the busy logic below mints a currentTurnId (it does for /compact at idle).
+    const timelineStatus = typeof update !== "string" ? update.timeline?.status : undefined;
+    if (timelineStatus === "compacting") {
+      this.compactionMidTurn = this.currentTurnId !== undefined;
+    } else if (timelineStatus === "compacted") {
+      this.publishCompactionNotice();
+      if (this.compactionMidTurn) {
+        // Keep the turn (and its live reasoning tail) alive; the genuine Stop hook ends it.
+        // pendingTimelineEvent (the marker) was set above and is consumed by publishStatus.
+        this.sessionLog(`compaction completed mid-turn (turn ${this.currentTurnId ?? "?"}) — staying busy`);
+        this.publishStatus();
+        return;
+      }
+    }
     if (status === "busy" && reason === "provider-turn") {
       if (!this.currentTurnId) {
         this.currentTurnId = typeof update !== "string" && update.id ? update.id : crypto.randomUUID();
         this.currentTurnStartedAt = Date.now();
+        this.compactionMidTurn = false;
         this.sessionLog(`turn started (turn ${this.currentTurnId})`);
       }
       this.armBusyReconciler();
@@ -1103,6 +1147,7 @@ export class AgentRunner {
       if (this.currentTurnId) this.sessionLog(`turn ended via provider idle (turn ${this.currentTurnId})`);
       this.currentTurnId = undefined;
       this.currentTurnStartedAt = undefined;
+      this.compactionMidTurn = false;
       this.disarmBusyReconciler();
       this.stopReasoningTail();
     }
@@ -1219,8 +1264,12 @@ export class AgentRunner {
     // retried until it lands. occurredAt is stamped now so a queued event reports when it
     // truly happened, not when the server finally accepted it. Routed through the fast-lane
     // sessionOutbox (#332) so a transient trace failure can't head-of-line block real messages.
+    // A stepId-bearing step (Codex tool running→completed, streamed reasoning/response) uses a
+    // STABLE idempotency key so the server upserts the row in place instead of appending a dup.
+    const stepId = input.session.stepId;
     this.sessionOutbox.enqueue({
       kind: "session-message",
+      ...(stepId ? { idempotencyKey: `session-step:${input.from}:${input.session.turnId ?? ""}:${stepId}` } : {}),
       payload: {
         from: input.from,
         to: input.to,
@@ -1514,6 +1563,7 @@ export class AgentRunner {
         ...(event.label ? { label: event.label } : {}),
         ...(event.status ? { status: event.status } : {}),
         ...(event.streaming !== undefined ? { streaming: event.streaming } : {}),
+        ...(event.stepId ? { stepId: event.stepId } : {}),
       },
     });
   }
@@ -1597,6 +1647,7 @@ export class AgentRunner {
     this.sessionLog(`force-clearing stuck provider-turn (${reason})`);
     this.claims.clearWorkKind("provider-turn");
     this.currentTurnId = undefined;
+    this.compactionMidTurn = false;
     this.publishStatus();
   }
 
@@ -1677,13 +1728,26 @@ export class AgentRunner {
     this.reasoningTail = undefined;
   }
 
+  // Mirror a discreet, durable "context compacted" marker into chat via the existing
+  // session-mirror lane (not a parallel channel). `notice` renders as an inline timeline
+  // marker (never a bubble) and survives reload, unlike the ephemeral timeline-status one.
+  private publishCompactionNotice(): void {
+    this.publishSessionEvent({
+      from: this.agentId,
+      to: "user",
+      body: "🗜 Context compacted",
+      session: { type: "notice", origin: "provider", label: "compacted", ...(this.currentTurnId ? { turnId: this.currentTurnId } : {}) },
+    });
+  }
+
   private publishStatus(): void {
     this.claims.expire();
     const status = this.claims.currentStatus();
     const agentStatus = runnerAgentStatus(status);
     const activeWork = this.claims.activeWork();
     const activeSubagents = activeWork.filter((item) => item.kind === "subagent");
-    const providerState = providerStateFromActiveWork(activeWork);
+    const terminalFailure = this.terminalFailure;
+    const providerState = terminalFailure?.providerState ?? providerStateFromActiveWork(activeWork);
     this.bus.setSemanticStatus(status === "offline" || status === "error" ? "idle" : status);
     const timelineEvent = this.pendingTimelineEvent;
     this.pendingTimelineEvent = undefined;
@@ -1704,6 +1768,11 @@ export class AgentRunner {
         lifecycleAction: this.lifecycleAction ?? null,
         profile: this.options.profile ?? null,
         ...(status === "error" ? { terminalStatus: "error" } : {}),
+        ...(terminalFailure ? {
+          lastError: terminalFailure.message,
+          terminalFailureReason: terminalFailure.reason,
+          terminalFailureMessage: terminalFailure.message,
+        } : {}),
         busyReasons: this.claims.reasons(),
         activeWork,
         activeSubagents,