agent-relay-runner 0.127.5 → 0.127.6

package/src/runner-core.ts

@@ -1,6 +1,5 @@
 import { hostname } from "node:os";
 import { mkdirSync, writeFileSync } from "node:fs";
-import { readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import type { AgentLifecycle, AgentProfile, ContextState, Message, MessageSessionMeta, ProviderState, SendMessageInput, TaskStatusInput, WorkspaceMetadata } from "agent-relay-sdk";
 import { errMessage, RelayBusClient, RelayHttpClient } from "agent-relay-sdk";
@@ -8,16 +7,14 @@ import { contextStateFromProbeMetrics, quotaStateFromProbeMetrics } from "agent-
 import { isPidAlive } from "agent-relay-sdk/process-utils";
 import { providerAttachmentText, providerMessageText } from "./adapter";
 import { computeLivenessSignal, type LivenessInputs } from "./liveness";
-import type { ManagedProcess, ProviderAdapter, ProviderConfig, ProviderPermissionDecision, ProviderPermissionDecisionInput, ProviderSessionEvent, ProviderStatusUpdate, RunnerSpawnConfig, SemanticStatus, TerminalAttachSpec } from "./adapter";
+import type { ManagedProcess, ProviderAdapter, ProviderConfig, ProviderPermissionDecision, ProviderPermissionDecisionInput, ProviderSessionEvent, ProviderSessionEventBatch, ProviderSessionTurnContext, ProviderSessionTurnInput, ProviderStatusUpdate, ProviderUserPromptInput, RunnerSpawnConfig, SemanticStatus, TerminalAttachSpec } from "./adapter";
 import { messagesWithCachedAttachments } from "./attachment-cache";
 import { ClaimTracker } from "./claim-tracker";
-import { ClaudeQuotaHarvest } from "./adapters/claude-quota-harvest";
+import { ProviderQuotaHarvest } from "./adapters/provider-quota-harvest";
 import { readRunnerContextProbeState } from "./context-probe-state";
 import { startControlServer, type ControlServer, type ResolvedPermissionPrompt } from "./control-server";
 import { ReplyObligationCache, obligationRequiresExplicitReply, responseCaptureReplyRoute } from "./reply-obligation-cache";
 import { Outbox, type OutboxRecord } from "./outbox";
-import { extractLastAssistantTurn, extractLastAssistantTurnAfterEntry, extractAssistantTurnForPrompt, countTranscriptEntries, extractHookAssistantMessage, extractLatestTurnSteps, stepDedupKeys, transcriptHasToolUseAnchor, transcriptLooksComplete } from "./adapters/claude-transcript";
-import { IncrementalClaudeTranscriptTail } from "./adapters/claude-transcript-tail";
 import { getManifest } from "agent-relay-providers";
 import { profileUsesProviderHostGlobals } from "./profile-home";
 import { RELAY_MCP_TOKEN_ENV, relayMcpEndpoint, resolveSharedMcpUrl } from "./relay-mcp";
@@ -45,7 +42,12 @@ import {
   isHttpAuthError,
   isHttpStatusError,
   lifecycleCapabilities,
+  providerExitLastError,
   providerExitDiagnostics,
+  providerExitResumeId,
+  providerManualRecoveryMessage,
+  providerManualRecoveryReason,
+  providerMonitorUnavailableMessage,
   providerStateFromActiveWork,
   registerWithinDeadline,
   relayBusUrl,
@@ -149,16 +151,9 @@ const RELAY_INJECTION_MARKERS = ["[relay message #", "[agent-relay", "<task-noti
 const INITIAL_PROMPT_FIRST_READY_TIMEOUT_MS = 30_000;
 const INITIAL_PROMPT_RETRY_READY_TIMEOUT_MS = 10_000;
 const MAX_INITIAL_PROMPT_ATTEMPTS = 6;
-// Reasoning tailer poll cadence (item 5). Coarse on purpose — reasoning is a
-// discreet progress signal, not a token stream; each tick reads only appended
-// transcript bytes.
-const REASONING_POLL_MS = 1_200;
 const SESSION_MIRROR_BATCH_MAX = 100;
-// #1116: bounded settle-poll for the PreToolUse pre-flush anchor. Claude's JSONL flush is
-// async/bursty and can lag the hook firing by a long margin, so a one-shot read (the old
-// #435/#499 behavior) often finds nothing. Poll at this cadence until the exact triggering
-// tool_use entry lands on disk, but never past the timeout — the question must never block
-// the user more than a few seconds waiting on a transcript write that might not be coming.
+// #1116: bounded settle-poll for provider pre-flush anchors. The adapter owns the
+// source-specific read; the runner owns the shared timeout knobs.
 const SETTLE_POLL_INTERVAL_MS = 250;
 const SETTLE_POLL_TIMEOUT_MS = 4_000;
 interface RunnerTimelineEvent {
@@ -171,11 +166,6 @@ interface RunnerTimelineEvent {
   metadata?: Record<string, unknown>;
 }
 
-interface ReasoningTailState {
-  timer: ReturnType<typeof setInterval>; emittedNarrationKeys: Set<string>;
-  poll(): Promise<void>;
-}
-
 export class AgentRunner {
   private readonly agentId: string;
   private readonly claims = new ClaimTracker();
@@ -196,7 +186,7 @@ export class AgentRunner {
   private sessionBatchSeq = 0;
   private readonly insights: RunnerInsights;
   private readonly busyReconciler: BusyReconciler;
-  private readonly claudeQuotaHarvest: ClaudeQuotaHarvest;
+  private readonly providerQuotaHarvest: ProviderQuotaHarvest;
   private currentToken?: string;
   private currentTokenJti?: string;
   private currentTokenProfileId?: string;
@@ -213,7 +203,7 @@ export class AgentRunner {
   private readonly mcpProxySecret: string;
   private process?: ManagedProcess;
   private stopped = false;
-  // #633 — set when the provider terminally exits but the runner stays alive (Claude native
+  // #633 — set when the provider terminally exits but the runner stays alive (native
   // auto-compaction / manual-resume hold). Rides on the offline status frame so the server fires a
   // terminal `agent.exited` event with a #636 diagnosis instead of the death going silent. Cleared
   // on any genuine restart back to busy/idle.
@@ -261,12 +251,8 @@ export class AgentRunner {
   private currentTurnId?: string;
   private currentTurnStartedAt?: number;
   private completedProviderTurns = 0;
-  // #435: high-water-mark for the pre-turn narrative flush. Counts how many
-  // valid JSONL entries were in the transcript at last pre-flush time so the
-  // Stop-hook capture (full mode) can skip what was already emitted.
-  private narrativeFlushEntryCount = 0;
-  // 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
+  // True while a turn that was already in flight is being compacted. Some providers
+  // post a transient idle after compaction even though the turn resumes 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).
@@ -291,16 +277,13 @@ export class AgentRunner {
   // wakes one) so the blocked badge lifts on its own.
   private rateLimitHold?: ProviderState;
   private pendingRateLimitHold?: ProviderState;
-  // 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?: ReasoningTailState;
   // Settle-poll cadence for the pre-flush anchor (#1116) — instance fields (not just the
   // module constants) so tests can shrink them without waiting out the real bound.
   private settlePollIntervalMs = SETTLE_POLL_INTERVAL_MS;
   private settlePollTimeoutMs = SETTLE_POLL_TIMEOUT_MS;
   private scratch?: SessionScratchLayout;
-  // #417: for non-claude providers, tracks how many times each spawner obligation has
-  // been re-injected so a non-responsive agent can't spin in a re-injection loop.
+  // #417: tracks how many times each spawner obligation has been re-injected so a
+  // non-responsive provider can't spin in a re-injection loop.
   private readonly pendingObligationInjections = new Map<number, number>();
 
   constructor(private readonly options: RunnerOptions) {
@@ -321,7 +304,7 @@ export class AgentRunner {
     this.mcpProxySecret = crypto.randomUUID();
     const runtime = runtimeMetadata(options.provider);
     this.http = new RelayHttpClient({ baseUrl: options.relayUrl, token: this.currentToken });
-    this.claudeQuotaHarvest = new ClaudeQuotaHarvest({ agentId: this.agentId, provider: options.provider, http: () => this.http });
+    this.providerQuotaHarvest = new ProviderQuotaHarvest({ agentId: this.agentId, provider: options.provider, http: () => this.http });
     this.obligationCache = new ReplyObligationCache({ fetch: () => this.http.listReplyObligations(this.agentId) });
     // Co-locate the durable outbox with the runner's runtime state (survives reboot) when the
     // orchestrator told us where that is; otherwise the Outbox falls back to a temp dir.
@@ -347,6 +330,7 @@ export class AgentRunner {
       getLastTranscriptPath: () => this.lastTranscriptPath,
       sessionLog: (message) => this.sessionLog(message),
     });
+    this.registerProviderSessionRoutes();
     this.busyReconciler = new BusyReconciler({
       isStopped: () => this.stopped,
       hasProcess: () => Boolean(this.process),
@@ -431,6 +415,11 @@ export class AgentRunner {
     return this.agentId;
   }
 
+  private registerProviderSessionRoutes(): void {
+    this.options.adapter.onSessionEvent?.((event) => { void this.publishProviderSessionEvent(event); });
+    this.options.adapter.onSessionEvents?.((events) => { void this.publishProviderSessionEvents(events); });
+  }
+
   async run(): Promise<void> {
     this.control = startControlServer({
       onStatus: (status) => this.setProviderStatus(status),
@@ -445,6 +434,10 @@ export class AgentRunner {
       onHookFatal: (report) => this.reportHookFatal(report),
       instanceId: this.options.instanceId,
       pendingPermissionStore: this.pendingPermissionStore,
+      permissionPromptHandler: this.options.adapter.permissionPromptHandler,
+      providerSourceId: this.options.adapter.statusSourceId ?? this.options.provider,
+      stopObligationPath: this.options.adapter.stopObligationPath,
+      monitorUnavailableMessage: providerMonitorUnavailableMessage(this.options.provider),
     });
     this.startMcpProxy();
     this.writeRunnerInfoFile();
@@ -458,7 +451,7 @@ export class AgentRunner {
       this.setProviderStatus(status);
       if (runnerShouldResolveProviderExit(semanticStatus, this.exitCommandInProgress)) this.options.onProviderExit?.(semanticStatus === "offline" ? 0 : 1);
     });
-    this.options.adapter.onSessionEvent?.((event) => { void this.publishProviderSessionEvent(event); });
+    this.registerProviderSessionRoutes();
     this.bus.on("message.new", (message) => {
       // A delivered message may create a new reply obligation — warm the snapshot so the
       // next turn-end sees it without a hot-path server read.
@@ -992,7 +985,7 @@ export class AgentRunner {
       // 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
+      // provider capture source 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"),
@@ -1026,7 +1019,7 @@ export class AgentRunner {
       }
 
       if (this.shouldStopUnexpectedProviderExit(diagnostics)) {
-        const hasResumeId = typeof diagnostics.claudeResumeId === "string" && diagnostics.claudeResumeId.length > 0;
+        const hasResumeId = providerExitResumeId(diagnostics) !== undefined;
         if (!hasResumeId) {
           const recoveredStatus = await this.recoveredStatusAfterUndeterminedProviderExit();
           if (recoveredStatus) {
@@ -1060,14 +1053,12 @@ export class AgentRunner {
             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.",
+            body: providerManualRecoveryMessage(this.options.provider, diagnostics),
             icon: "ti-player-stop",
             metadata: {
               eventType: "provider.restart_decision",
               decision: "stop-surface",
-              reason: hasResumeId ? "claude-exit-manual-resume-available" : "claude-exit-manual-intervention-required",
+              reason: providerManualRecoveryReason(diagnostics),
               ...diagnostics,
             },
           });
@@ -1077,7 +1068,7 @@ export class AgentRunner {
           // status frame (published by setProviderStatus below) carries it; the server's bus status
           // handler turns that edge into a terminal `agent.exited` event with a #636 diagnosis.
           this.terminalProviderExit = {
-            reason: hasResumeId ? "claude-exit-manual-resume-available" : "claude-exit-manual-intervention-required",
+            reason: providerManualRecoveryReason(diagnostics),
             ...diagnostics,
           };
           this.setProviderStatus({
@@ -1247,7 +1238,7 @@ export class AgentRunner {
       // A rate-limit hold persists across the idle the turn ends on; any other
       // providerState supersedes it (clears a stale hold).
       if (ps.state === "blocked" && ps.reason === "rate_limit") {
-        const paneRateLimitHold = typeof ps.source === "string" && ps.source.startsWith("claude-pane");
+        const paneRateLimitHold = typeof ps.source === "string" && ps.source.startsWith(`${this.options.adapter.statusSourceId ?? this.options.provider}-pane`);
         if (status === "idle" && reason === "provider-turn" && paneRateLimitHold && this.claims.activeWork().some((work) => work.kind === "provider-turn")) {
           this.pendingRateLimitHold = update.providerState;
           this.providerBlocked = false;
@@ -1296,7 +1287,7 @@ export class AgentRunner {
     } else if (status === "idle" || status === "busy") {
       this.terminalFailure = undefined;
     }
-    // Compaction lifecycle (Claude PreCompact→`compacting` busy / PostCompact→`compacted`
+    // Compaction lifecycle (`compacting` busy / `compacted` idle timeline) is separate
     // 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).
@@ -1316,10 +1307,8 @@ export class AgentRunner {
     }
     if (status === "busy" && reason === "provider-turn") {
       if (!this.currentTurnId) {
-        // For Claude, `update.id` carries the native prompt_id the UserPromptSubmit
-        // hook reported (relay-status.sh → /status) — the same id the Stop hook and
-        // transcript use for this turn. Falls back to a random mint only when no
-        // native id was supplied (e.g. a provider/path that doesn't report one).
+        // `update.id` carries a provider-native turn id when available. Falls back
+        // to a random mint only when no native id was supplied.
         this.currentTurnId = typeof update !== "string" && update.id ? update.id : crypto.randomUUID();
         this.currentTurnStartedAt = Date.now();
         this.compactionMidTurn = false;
@@ -1400,16 +1389,15 @@ export class AgentRunner {
     this.publishStatus();
   }
 
-  // #417: when a non-claude provider finishes a turn with a pending spawner obligation
-  // still unresolved, re-inject the obligation as a synthetic message so providerMessageText
-  // surfaces the specific `agent-relay /reply <id>` command. Claude handles this via the
-  // stop.sh hook; every other provider needs this in-process nudge.
+  // #417: when a provider finishes a turn with a pending spawner obligation still
+  // unresolved, re-inject the obligation as a synthetic message so providerMessageText
+  // surfaces the specific `agent-relay /reply <id>` command.
   private async reInjectPendingObligation(): Promise<void> {
     if (!this.process) return;
-    // Filter to spawner obligations only — user obligations go through the existing codex
+    // Filter to spawner obligations only — user obligations go through the existing
     // prompt-capture path (publishProviderSessionEvent) and the session mirror (#418), never
-    // an explicit /reply. Shared predicate so this rule stays in lockstep with the Claude
-    // Stop-hook nag exemption (control-server.replyObligationStopDecision).
+      // an explicit /reply. Shared predicate so this rule stays in lockstep with
+      // the stop-hook nag exemption (control-server.replyObligationStopDecision).
     const obligations = this.obligationCache.get().filter(obligationRequiresExplicitReply);
     if (!obligations.length) return;
     const MAX_REINJECTIONS = 3;
@@ -1429,7 +1417,7 @@ export class AgentRunner {
         readBy: [] as string[],
         createdAt: obligation.createdAt,
       };
-      // Suppress the userMessage echo that providers (e.g. Codex) reflect back when
+      // Suppress the userMessage echo that providers can reflect back when
       // a turn is started with relay-formatted content — the echo body is exactly what
       // providerMessageText produces, which starts with "[relay message #" and is caught
       // by the RELAY_INJECTION_MARKERS prefix check, but record it explicitly as
@@ -1445,131 +1433,25 @@ export class AgentRunner {
     }
   }
 
-  // Session-mirror lane: capture the assistant turn from the Claude transcript and
-  // post it as a "session" message so it shows in the dashboard chat with zero
-  // agent tokens. Capture is UNCONDITIONAL — it no longer depends on a triggering
-  // relay message existing, so turns started from the web terminal (which create
-  // no relay message) are mirrored too. A reply obligation, when present, is still
-  // used as replyTo so the Stop hook stops nagging the agent to /reply.
-  //
-  // isPreFlush: true (#435/#499/#1116) — mid-turn PreToolUse boundary. Settle-polls the
-  // transcript for the exact tool_use entry that triggered the hook (toolName/toolInput,
-  // the hook payload's own anchor), then drains the live tail and force-flushes session
-  // messages before showing the blocking control; the entry cursor lets Stop capture skip
-  // already-emitted text. Returns whether the settle-poll actually found the anchor
-  // (reasoningSettled) — an honest `false` on timeout rather than a stamped `true` on a
-  // premise nothing here confirmed (#1116; see InteractivePrompt.reasoningSettled).
-  private async publishSessionTurn(input: { transcriptPath: string; lastAssistantMessage?: unknown; promptId?: string; isPreFlush?: boolean; toolName?: string; toolInput?: unknown }): Promise<{ reasoningSettled: boolean } | void> {
+  private async publishSessionTurn(input: ProviderSessionTurnInput): Promise<{ reasoningSettled: boolean } | void> {
     if (input.transcriptPath) this.lastTranscriptPath = input.transcriptPath;
-
-    if (input.isPreFlush) {
-      if (!input.transcriptPath) return { reasoningSettled: true };
-      const settled = await this.settlePollForToolUse(input.transcriptPath, input.toolName, input.toolInput);
-      const jsonl = settled.jsonl;
-      if (jsonl === undefined) return { reasoningSettled: false };
-      const body = extractLastAssistantTurnAfterEntry(jsonl, this.narrativeFlushEntryCount);
-      await this.drainReasoningTail();
-      this.narrativeFlushEntryCount = countTranscriptEntries(jsonl);
-      if (body && !this.preFlushBodyAlreadyMirroredByReasoningTail(jsonl, body)) {
-        const turnId = this.currentTurnId;
-        this.sessionLog(`pre-flush narrative for turn ${turnId ?? "?"} (${body.length} chars)`);
-        await this.publishSessionEvent({ from: this.agentId, to: "user", body, session: { type: "response", origin: "provider", ...(turnId ? { turnId } : {}) } });
-      }
-      await this.sessionOutbox.flush(2_000).then((ok) => { if (!ok) this.sessionLog(`pre-flush session outbox incomplete before blocking control (${this.sessionOutbox.pendingCount()} pending)`); }, (error) => this.sessionLog(`pre-flush session outbox failed before blocking control: ${errMessage(error)}`));
-      return { reasoningSettled: settled.settled };
-    }
-
-    // Claude's Stop hook reports its own native `prompt_id` — the same UUID the
-    // transcript stamps on every entry of this turn (extractAssistantTurnForPrompt /
-    // resolveEntryPromptId in claude-transcript.ts). It's the authoritative turn
-    // identifier; currentTurnId should already equal it (seeded from the same
-    // prompt_id at turn start — see setProviderStatus / handleUserPrompt), but this
-    // prefers the freshest source so finalization is correct even if the two drift.
-    const turnId = input.promptId ?? this.currentTurnId;
-    // #1116: drain whatever the tail hasn't polled yet BEFORE stopping it — stopping first
-    // (the old order) clears the poll/timer state, so any steps Claude flushed in the last
-    // window between the tail's previous tick and this Stop hook were silently dropped from
-    // the step lane instead of reaching chat.
-    await this.drainReasoningTail();
-    this.stopReasoningTail();
-    // Optional correlation for threading + obligation clearing — never a capture gate.
-    let replyToMessageId: number | undefined, replyTarget = "user";
-    const pendingPrompt = this.pendingPromptMessageId;
-    if (pendingPrompt) {
-      replyToMessageId = pendingPrompt;
-      this.pendingPromptMessageId = undefined;
-    } else {
-      // Correlation-only (threading + obligation clearing) — the local snapshot is fresh
-      // enough and never blocks the response-capture path (#196).
-      const route = responseCaptureReplyRoute(this.obligationCache.get(), this.currentTurnStartedAt);
-      replyToMessageId = route?.replyToMessageId; replyTarget = route?.to ?? "user";
-    }
-
-    // Grab and reset the pre-flush cursor before extraction: the cursor may be
-    // non-zero when a PreToolUse hook flushed narrative earlier this turn (#435).
-    // In "full" mode, skip those already-emitted entries so they don't duplicate.
-    const flushCount = this.narrativeFlushEntryCount;
-    this.narrativeFlushEntryCount = 0;
-
-    // PRIMARY capture source: the Stop hook's own last_assistant_message. Claude
-    // reports it synchronously in the hook payload itself, so there is no
-    // transcript file-read race to retry against — this text is authoritative and
-    // complete the moment the hook fires. The transcript is read at most ONCE
-    // (never retried/looped) and only to enrich "full" mode with the turn's
-    // intermediate narration; if that single read comes up empty (the file simply
-    // hasn't caught up yet) the hook payload text still carries the turn.
-    let body = extractHookAssistantMessage(input.lastAssistantMessage);
-    if (this.options.providerConfig.chatCaptureMode === "full" && input.transcriptPath) {
-      let jsonl: string | undefined;
-      try { jsonl = await readFile(input.transcriptPath, "utf8"); } catch { jsonl = undefined; }
-      if (jsonl !== undefined && transcriptLooksComplete(jsonl)) {
-        // Deterministic slicing via prompt_id→parentUuid chaining when the native id is
-        // known; only fall back to the legacy "last real user prompt" heuristic when that
-        // deterministic slice comes up EMPTY, not merely when turnId is falsy — an old
-        // Claude (<2.1.196) mints a truthy random turnId that never resolves via promptId
-        // chaining, so branching on truthiness alone left this fallback unreachable and
-        // silently dropped intermediate narration in full mode (#1086 review, Finding F1).
-        let full = turnId ? extractAssistantTurnForPrompt(jsonl, turnId, flushCount) : "";
-        if (!full) full = flushCount > 0 ? extractLastAssistantTurnAfterEntry(jsonl, flushCount) : extractLastAssistantTurn(jsonl);
-        if (full) body = full;
-      }
-    }
-    // Last-resort safety net for the default "final" mode (#1086 review, Finding F2):
-    // last_assistant_message is an undocumented Claude hook field. If a future Claude
-    // version renames or drops it, do ONE (never retried — same one-shot discipline as the
-    // "full" mode enrichment above) transcript read rather than silently losing every
-    // capture in the mode nearly every provider config runs in.
-    if (!body && this.options.providerConfig.chatCaptureMode === "final" && input.transcriptPath) {
-      let jsonl: string | undefined;
-      try { jsonl = await readFile(input.transcriptPath, "utf8"); } catch { jsonl = undefined; }
-      if (jsonl !== undefined) {
-        const fallback = turnId ? extractAssistantTurnForPrompt(jsonl, turnId, flushCount) : "";
-        body = fallback || (flushCount > 0 ? extractLastAssistantTurnAfterEntry(jsonl, flushCount) : extractLastAssistantTurn(jsonl));
-      }
-    }
-    // A pure tool-use turn with no closing text is fine to skip — its reasoning and
-    // tool steps already carried the visibility into chat.
-    if (!body) {
-      this.sessionLog(`response capture: no closing text for turn ${turnId ?? "?"} (skipped)`);
-      return;
-    }
-
-    this.sessionLog(`response captured for turn ${turnId ?? "?"} (${body.length} chars${replyToMessageId ? `, replyTo #${replyToMessageId}` : ", no replyTo"})`);
-    await publishCapturedResponse({
-      publishSessionEvent: (event) => this.publishSessionEvent(event),
-      outbox: this.sessionOutbox,
-      provider: this.options.provider,
-      from: this.agentId,
-      to: replyTarget,
-      body,
-      replyTo: replyToMessageId,
-      // A Stop-hook-driven capture is by construction a definitive, provider-native
-      // turn completion — Claude's own lifecycle hook fired, not a reconstructed guess.
-      session: { type: "response", origin: "provider", final: true, confidence: "definitive", endedBy: "completed", ...(turnId ? { turnId } : {}) },
-    });
-    // The agent's reply may have cleared an obligation — refresh the snapshot so the next
-    // turn-end doesn't re-prompt for a message already answered (#196).
-    if (replyToMessageId) this.obligationCache.markDirty();
+    const result = await this.options.adapter.captureSessionTurn?.(input, this.sessionTurnContext());
+    return typeof result?.reasoningSettled === "boolean" ? { reasoningSettled: result.reasoningSettled } : undefined;
+  }
+
+  private sessionTurnContext(): ProviderSessionTurnContext {
+    return {
+      turnId: this.currentTurnId,
+      turnStartedAt: this.currentTurnStartedAt,
+      chatCaptureMode: this.options.providerConfig.chatCaptureMode,
+      reasoningCapture: this.options.providerConfig.reasoningCapture,
+      settlePollIntervalMs: this.settlePollIntervalMs,
+      settlePollTimeoutMs: this.settlePollTimeoutMs,
+      flushSessionEvents: (timeoutMs) => this.sessionOutbox.flush(timeoutMs),
+      pendingSessionEventCount: () => this.sessionOutbox.pendingCount(),
+      log: (message) => this.sessionLog(message),
+      debug: (message) => this.sessionDebug(message),
+    };
   }
 
   // Post one session-mirror event (prompt echo, assistant response, reasoning or
@@ -1582,7 +1464,7 @@ export class AgentRunner {
     // provider-native event time; otherwise the outbox stamps enqueue time. 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
+    // A stepId-bearing step (tool running to 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({
@@ -1663,18 +1545,9 @@ export class AgentRunner {
     }
   }
 
-  // A human typed a prompt directly into the provider (web terminal / TUI). Mirror
-  // it into the dashboard chat so both surfaces stay in sync, and kick off reasoning
-  // tailing for the turn. Skips prompts the runner itself injected (chat box, relay
-  // deliveries) so those aren't double-posted.
-  private async handleUserPrompt(input: { prompt: string; transcriptPath?: string; promptId?: string }): Promise<void> {
+  private async handleUserPrompt(input: ProviderUserPromptInput): Promise<void> {
     if (input.transcriptPath) this.lastTranscriptPath = input.transcriptPath;
     if (!this.currentTurnId) {
-      // Claude's own prompt_id (from the UserPromptSubmit hook payload) is the
-      // native, stable turn identifier — the same id the Stop hook reports and the
-      // transcript stamps on every entry of this turn. Falls back to a random mint
-      // only for the rare case prompt_id wasn't available (see the ZS base schema
-      // note: absent until the very first user input of the process lifetime).
       this.currentTurnId = input.promptId ?? crypto.randomUUID();
       this.currentTurnStartedAt = Date.now();
     }
@@ -1690,10 +1563,10 @@ export class AgentRunner {
     } else if (text) {
       this.sessionDebug("user-prompt hook: skipped echo (runner-injected)");
     }
-    if (input.transcriptPath) this.startReasoningTail(input.transcriptPath);
+    await this.options.adapter.handleUserPrompt?.(input, this.sessionTurnContext());
   }
 
-  // A provider lifecycle hook reported a session boundary (Claude PreCompact / SessionEnd
+  // A provider lifecycle hook reported a session boundary
   // → control server). Normalize the raw provider reason to a SessionDestroyReason and run
   // the same pre-destroy seam the bus commands use. `clear`/`compact` continue the session;
   // anything else (logout, prompt_input_exit, other) is a real termination.
@@ -1701,8 +1574,8 @@ export class AgentRunner {
     // Reason mapping is fail-safe-toward-termination: only the two known session-
     // CONTINUING reasons are special-cased; everything else (logout, prompt_input_exit,
     // other, AND any future reason) maps to "shutdown" → full pre-destroy capture.
-    // ⚠ If Claude Code adds a new BENIGN/continuing boundary reason, add it here — until
-    // then it will trigger a (harmless but wasteful) full context capture on a session
+    // If a provider adds a new benign/continuing boundary reason, add it here. Until
+    // then it will trigger a harmless but wasteful full context capture on a session
     // that isn't actually ending.
     const reason = input.reason === "compact" ? "compact"
       : input.reason === "clear" ? "clear"
@@ -1780,10 +1653,9 @@ export class AgentRunner {
     await this.insights.captureContextRatio(reason, opts);
   }
 
-  // Route a provider-emitted session event (Codex app-server) into the chat mirror.
-  // Mirrors the same semantics as the Claude lane: prompts are echoed with dedup,
-  // and a response is only auto-captured when the agent won't separately reply to a
-  // relay obligation (so relay-triggered turns aren't double-posted).
+  // Route a provider-emitted session event into the chat mirror.
+  // Mirrors provider session events into chat. Prompts are echoed with dedup, and
+  // response routing clears only the obligations the adapter says its capture can satisfy.
   private async publishProviderSessionEvent(event: ProviderSessionEvent): Promise<void> {
     const body = event.body.trim();
     if (!body) return;
@@ -1795,6 +1667,17 @@ export class AgentRunner {
         to: this.agentId,
         body,
         session: { type: "prompt", origin: event.origin ?? "terminal", ...(turnId ? { turnId } : {}) },
+        ...(event.occurredAt ? { occurredAt: event.occurredAt } : {}),
+      });
+      return;
+    }
+    if (event.type === "response" && event.final === false) {
+      await this.publishSessionEvent({
+        from: this.agentId,
+        to: "user",
+        body,
+        ...(event.occurredAt ? { occurredAt: event.occurredAt } : {}),
+        session: { type: "response", origin: event.origin ?? "provider", ...(turnId ? { turnId } : {}) },
       });
       return;
     }
@@ -1803,7 +1686,7 @@ export class AgentRunner {
       // response. User obligations still belong to the session mirror; spawner
       // obligations (#413) route to the spawn-parent with replyTo to clear the debt.
       // #1083: a turn-final capture is ALWAYS mirrored, regardless of reply route — an
-      // autonomous Codex turn with no pending prompt and no eligible obligation used to
+      // autonomous provider turn with no pending prompt and no eligible obligation used to
       // hit `if (!route) return` here and vanish before ever reaching publishCapturedResponse,
       // so it was neither shown in the dashboard nor eligible for report-up. The route only
       // decides whether an explicit reply/obligation-clear also happens; when there's none,
@@ -1816,18 +1699,38 @@ export class AgentRunner {
         replyToMessageId = pendingPrompt;
         this.pendingPromptMessageId = undefined;
       } else {
-        const route = responseCaptureReplyRoute(this.obligationCache.get(), this.currentTurnStartedAt, { suppressUser: true });
+        const route = responseCaptureReplyRoute(this.obligationCache.get(), this.currentTurnStartedAt, { suppressUser: event.replyToUserObligation !== true });
         if (route) { replyToMessageId = route.replyToMessageId; replyTarget = route.to; }
       }
-      await publishCapturedResponse({ publishSessionEvent: (sessionEvent) => this.publishSessionEvent(sessionEvent), outbox: this.sessionOutbox, provider: this.options.provider, from: this.agentId, to: replyTarget, body, replyTo: replyToMessageId, session: { type: "response", origin: event.origin ?? "provider", ...(turnId ? { turnId } : {}), ...(event.confidence ? { confidence: event.confidence } : {}), ...(event.endedBy ? { endedBy: event.endedBy } : {}) } });
+      await publishCapturedResponse({ publishSessionEvent: (sessionEvent) => this.publishSessionEvent({ ...sessionEvent, ...(event.occurredAt ? { occurredAt: event.occurredAt } : {}) }), outbox: this.sessionOutbox, provider: this.options.provider, from: this.agentId, to: replyTarget, body, replyTo: replyToMessageId, session: { type: "response", origin: event.origin ?? "provider", ...(turnId ? { turnId } : {}), ...(event.confidence ? { confidence: event.confidence } : {}), ...(event.endedBy ? { endedBy: event.endedBy } : {}) } });
       if (replyToMessageId) this.obligationCache.markDirty();
       return;
     }
     if (this.options.providerConfig.reasoningCapture === false) return;
-    await this.publishSessionEvent({
+    this.publishSessionEvent(this.providerStepSessionInput(event, body, turnId));
+  }
+
+  private async publishProviderSessionEvents(events: ProviderSessionEventBatch): Promise<void> {
+    const inputs: Array<{ from: string; to: string; body: string; session: MessageSessionMeta; replyTo?: number; occurredAt?: number }> = [];
+    for (const event of events) {
+      const body = event.body.trim();
+      if (!body) continue;
+      if (event.type === "prompt" || event.type === "response") {
+        await this.publishProviderSessionEvent(event);
+        continue;
+      }
+      if (this.options.providerConfig.reasoningCapture === false) continue;
+      inputs.push(this.providerStepSessionInput(event, body, event.turnId ?? this.currentTurnId));
+    }
+    if (inputs.length) this.publishSessionEventsBatch(inputs);
+  }
+
+  private providerStepSessionInput(event: ProviderSessionEvent, body: string, turnId?: string): { from: string; to: string; body: string; session: MessageSessionMeta; occurredAt?: number } {
+    return {
       from: this.agentId,
       to: "user",
       body,
+      ...(event.occurredAt ? { occurredAt: event.occurredAt } : {}),
       session: {
         type: event.type,
         origin: event.origin ?? "provider",
@@ -1838,7 +1741,7 @@ export class AgentRunner {
         ...(event.stepId ? { stepId: event.stepId } : {}),
         ...(event.final ? { final: true } : {}),
       },
-    });
+    };
   }
 
   // Remember an injected prompt so its UserPromptSubmit echo can be suppressed. Prunes
@@ -1880,7 +1783,7 @@ export class AgentRunner {
   // #650: reconcile pid-bearing busy work against actual process liveness. A tracked
   // command/shell that dies out-of-band (killed by the operator, crashes, orphaned)
   // sends no exit event, so its busy marker would otherwise never clear and the agent
-  // shows `busy` forever — blocking transient auto-reap and (for Claude) holding quota.
+  // shows `busy` forever — blocking transient auto-reap and holding provider quota.
   // The timer self-disarms once no pid-bearing work remains; it is armed lazily when a
   // busy report carrying pids arrives, so idle/non-tracked agents pay nothing.
   private armBusyLivenessReconcile(): void {
@@ -1915,120 +1818,8 @@ export class AgentRunner {
     if (!this.claims.hasLivenessTrackedWork()) this.disarmBusyLivenessReconcile();
   }
 
-  // --- Turn-step tailer (item 5) ------------------------------------------------------
-  // Tail the in-flight turn's Claude transcript and surface new narration/reasoning/tool
-  // steps as session events, in transcript order. `narration` (the agent's intermediate
-  // text) is the primary visible content; reasoning visibility is a client-side toggle.
-  // Coalesced and coarse; the final response still comes through publishSessionTurn.
-  // `reasoningCapture: false` disables the whole live trace (server-side kill switch).
-  private startReasoningTail(transcriptPath: string): void {
-    if (this.options.providerConfig.reasoningCapture === false) return;
-    this.stopReasoningTail();
-    // Track emitted steps by content signature, not by index/count: the "latest
-    // turn" window in the transcript can shrink/reset (a tool_result entry, a
-    // mid-turn user line), and an index cursor would then either re-emit or stall
-    // and drop the rest of the turn. A seen-set is idempotent under any reshuffle.
-    // The signature is salted with each step's occurrence-within-window (stepDedupKeys)
-    // so two identical steps in one turn — same tool, same input — both surface (#265).
-    const seen = new Set<string>();
-    const emittedNarrationKeys = new Set<string>();
-    const transcriptTail = new IncrementalClaudeTranscriptTail();
-    const turnIdAtStart = this.currentTurnId;
-    // On the first poll the new prompt usually hasn't landed in the transcript yet,
-    // so extractLatestTurnSteps still returns the PRIOR (completed) turn. Seed those
-    // signatures as already-seen so we don't replay last turn's reasoning/tools as
-    // this turn's activity. Once our prompt lands the window resets at the new user
-    // boundary and genuinely-new steps emit normally. Only seed when the transcript
-    // is complete (last entry is an end_turn assistant) — otherwise we're already
-    // inside the new turn and those steps are legitimately ours.
-    let seeded = false;
-    let pendingPoll = Promise.resolve();
-    const pollBody = async (): Promise<void> => {
-      const result = await transcriptTail.poll(transcriptPath);
-      if (!result.available) return;
-      if (result.reset) { seen.clear(); emittedNarrationKeys.clear(); seeded = false; }
-      if (!result.changed && (seeded || (!result.steps.length && !result.transcriptLooksComplete))) return;
-      const keyed = stepDedupKeys(result.steps).map((sig, i) => ({ sig, step: result.steps[i]! }));
-      if (!seeded) {
-        seeded = true;
-        if (result.transcriptLooksComplete) {
-          for (const { sig } of keyed) seen.add(sig);
-        }
-      }
-      const turnId = this.currentTurnId ?? turnIdAtStart;
-      let emitted = 0;
-      const batch: Array<{ from: string; to: string; body: string; session: MessageSessionMeta; occurredAt?: number }> = [];
-      for (const { sig, step } of keyed) {
-        if (seen.has(sig)) continue;
-        seen.add(sig);
-        emitted += 1;
-        batch.push({
-          from: this.agentId,
-          to: "user",
-          body: step.text,
-          ...(step.occurredAt ? { occurredAt: step.occurredAt } : {}),
-          session: { type: step.type, origin: "provider", ...(turnId ? { turnId } : {}), ...(step.label ? { label: step.label } : {}) },
-        });
-        if (step.type === "narration") emittedNarrationKeys.add(sig);
-      }
-      this.publishSessionEventsBatch(batch);
-      if (emitted) this.sessionDebug(`reasoning tail emitted ${emitted} step(s) (turn ${turnId ?? "?"}, ${seen.size} total)`);
-    };
-    const poll = (): Promise<void> => {
-      const next = pendingPoll.then(pollBody, pollBody);
-      pendingPoll = next.catch(() => {});
-      return next;
-    };
-    this.reasoningTail = { emittedNarrationKeys, poll, timer: setInterval(() => { void poll(); }, REASONING_POLL_MS) };
-    this.sessionLog(`reasoning tail started (turn ${turnIdAtStart ?? "?"})`);
-    void poll();
-  }
-
-  private async drainReasoningTail(): Promise<void> {
-    if (this.options.providerConfig.reasoningCapture === false) return;
-    await this.reasoningTail?.poll();
-  }
-
-  // #1116: bounded settle-poll for the PreToolUse pre-flush anchor. The old pre-flush read
-  // the transcript exactly once and, on the false premise that Claude's JSONL write is
-  // synchronous with the hook firing, treated whatever it found (often nothing) as complete.
-  // Claude's flush is actually async/bursty — sometimes gated on the hook's own resolution —
-  // so this polls at settlePollIntervalMs until the transcript contains the EXACT tool_use
-  // entry that triggered the hook (toolName/toolInput from the hook payload is the precise
-  // anchor), then returns the freshest read. Never polls past settlePollTimeoutMs — the
-  // question must ship regardless, just honestly flagged as `settled: false` when it does.
-  // No toolName (a caller that can't identify an anchor) skips straight to a single read,
-  // matching the old one-shot behavior.
-  private async settlePollForToolUse(transcriptPath: string, toolName?: string, toolInput?: unknown): Promise<{ settled: boolean; jsonl?: string }> {
-    const deadline = Date.now() + this.settlePollTimeoutMs;
-    for (;;) {
-      let jsonl: string | undefined;
-      try { jsonl = await readFile(transcriptPath, "utf8"); } catch { jsonl = undefined; }
-      if (!toolName) return { settled: Boolean(jsonl), jsonl };
-      if (jsonl !== undefined && transcriptHasToolUseAnchor(jsonl, toolName, toolInput)) return { settled: true, jsonl };
-      if (Date.now() >= deadline) return { settled: false, jsonl };
-      await Bun.sleep(this.settlePollIntervalMs);
-    }
-  }
-
-  private preFlushBodyAlreadyMirroredByReasoningTail(jsonl: string, body: string): boolean {
-    const tail = this.reasoningTail;
-    if (!tail || !tail.emittedNarrationKeys.size) return false;
-    const steps = extractLatestTurnSteps(jsonl);
-    const keys = stepDedupKeys(steps);
-    const mirrored = steps
-      .map((step, index) => ({ step, key: keys[index]! }))
-      .filter(({ step, key }) => step.type === "narration" && tail.emittedNarrationKeys.has(key))
-      .map(({ step }) => step.text)
-      .join("\n\n")
-      .trim();
-    const trimmed = body.trim();
-    return mirrored === trimmed || mirrored.endsWith(`\n\n${trimmed}`);
-  }
-
   private stopReasoningTail(): void {
-    if (this.reasoningTail) clearInterval(this.reasoningTail.timer);
-    this.reasoningTail = undefined;
+    this.options.adapter.stopSessionTrace?.();
   }
 
   // Mirror a discreet, durable "context compacted" marker into chat via the existing
@@ -2142,9 +1933,7 @@ export class AgentRunner {
         // silent-death terminal event + #636 post-mortem.
         ...(this.terminalProviderExit ? {
           terminalProviderExit: this.terminalProviderExit,
-          ...(typeof this.terminalProviderExit.claudeResumeId === "string"
-            ? { lastError: `Claude provider exited; resume id ${this.terminalProviderExit.claudeResumeId} captured for manual recovery` }
-            : { lastError: "Claude provider exited; manual intervention required" }),
+          lastError: providerExitLastError(this.options.provider, this.terminalProviderExit),
         } : {}),
         busyReasons: staleProviderTurnBusy ? busyReasons.filter((reason) => reason !== "provider-turn") : busyReasons,
         completedProviderTurns: this.completedProviderTurns,
@@ -2185,7 +1974,7 @@ export class AgentRunner {
       await this.http.setStatus(this.agentId, agentStatus, this.options.instanceId);
       await this.http.setReady(this.agentId, agentStatus !== "offline", this.options.instanceId);
       await this.http.heartbeat(this.agentId, this.options.instanceId);
-      await this.claudeQuotaHarvest.publish().catch((error) => this.logRunnerDiagnostic(`passive Claude quota publish failed: ${errMessage(error)}`));
+      await this.providerQuotaHarvest.publish().catch((error) => this.logRunnerDiagnostic(`passive provider quota publish failed: ${errMessage(error)}`));
       await this.bootstrapUnreadMessages();
     } catch (error) {
       if (!this.stopped) this.handleHttpLivenessFailure(error);