agent-relay-server 0.124.0 → 0.126.0

package/runner/src/adapters/claude-transcript.ts

@@ -46,6 +46,16 @@ interface TranscriptEntry {
   // Events/countSubstantiveTurns) intentionally do NOT filter — changing them
   // would shift the #184/#185 baselines, a separate concern.
   isSidechain?: boolean;
+  // Every entry carries its own `uuid` and its `parentUuid` (the entry it was
+  // appended after), forming a causal chain for the whole session. A `user`-type
+  // entry — whether the real prompt or a synthetic tool_result — is stamped with
+  // `promptId`: the same UUID Claude's Stop-hook payload reports as `prompt_id`,
+  // shared by every entry from that prompt until the next one. Assistant entries
+  // don't carry `promptId` directly; their turn is resolved by walking `parentUuid`
+  // back to the nearest ancestor that has one (see resolveEntryPromptId).
+  uuid?: string;
+  parentUuid?: string;
+  promptId?: string;
 }
 
 function blocks(message: TranscriptMessage | undefined): TranscriptBlock[] {
@@ -147,59 +157,39 @@ export function extractLastAssistantTurnAfterEntry(jsonl: string, afterEntry: nu
 }
 
 /**
- * Count valid JSON entries in a JSONL string. Used to record the high-water-mark
- * after a pre-flush so the Stop hook knows where to resume in full-capture mode.
+ * Resolve the `promptId` (Stop hook's `prompt_id`) a transcript entry belongs to.
+ * A `user`-type entry (the real prompt, or a synthetic tool_result) carries its own
+ * `promptId`; an assistant entry doesn't, so its turn is resolved by walking
+ * `parentUuid` back through the causal chain until an ancestor with one is found.
+ * Returns undefined for an entry with no resolvable ancestor (e.g. the very first
+ * turn of a process, before any `promptId` has ever been stamped).
  */
-export function countTranscriptEntries(jsonl: string): number {
-  let count = 0;
-  for (const line of jsonl.split("\n")) {
-    if (!line.trim()) continue;
-    try { JSON.parse(line); count++; } catch {}
-  }
-  return count;
-}
-
-/**
- * Returns only the text from the LAST assistant entry in the current turn.
- * Unlike extractLastAssistantTurn which collects all intermediate text between
- * tool calls, this returns just the final response — what the user sees as the
- * concluding message.
- */
-export function extractFinalAssistantMessage(jsonl: string): string {
-  const lines = jsonl.split("\n");
-  let lastText = "";
-  let pastLastUserPrompt = false;
-  for (const line of lines) {
-    const trimmed = line.trim();
-    if (!trimmed) continue;
-    let entry: TranscriptEntry;
-    try {
-      entry = JSON.parse(trimmed) as TranscriptEntry;
-    } catch {
-      continue;
-    }
-    if (isSidechainEntry(entry)) continue;
-    if (isRealUserPrompt(entry)) {
-      pastLastUserPrompt = true;
-      lastText = "";
-      continue;
-    }
-    if (!pastLastUserPrompt) continue;
-    const text = assistantText(entry);
-    if (text) lastText = text;
+function resolveEntryPromptId(entry: TranscriptEntry, byUuid: ReadonlyMap<string, TranscriptEntry>): string | undefined {
+  let current: TranscriptEntry | undefined = entry;
+  const visited = new Set<string>();
+  while (current) {
+    if (typeof current.promptId === "string" && current.promptId) return current.promptId;
+    const parentUuid = current.parentUuid;
+    if (!parentUuid || visited.has(parentUuid)) return undefined;
+    visited.add(parentUuid);
+    current = byUuid.get(parentUuid);
   }
-  return lastText.trim();
+  return undefined;
 }
 
 /**
- * Like extractFinalAssistantMessage but skips the first `afterEntry` valid JSON
- * entries. Used when a PreToolUse pre-flush already emitted the text before a
- * blocking control, so final-mode Stop capture only sees later assistant text.
+ * Deterministic replacement for extractLastAssistantTurnAfterEntry's "walk back to
+ * the last real user prompt" heuristic: collects assistant `text` blocks for entries
+ * whose resolved promptId (see resolveEntryPromptId) equals the Claude-native
+ * `promptId` the Stop hook reported for this turn. Skips the first `afterEntry`
+ * entries the same way, for pre-flush resume. Since entries never move once
+ * written, a turn's promptId membership is exact — no text-shape guessing about
+ * what counts as a "real" prompt.
  */
-export function extractFinalAssistantMessageAfterEntry(jsonl: string, afterEntry: number): string {
+export function extractAssistantTurnForPrompt(jsonl: string, promptId: string, afterEntry = 0): string {
   const lines = jsonl.split("\n");
-  let lastText = "";
-  let pastLastUserPrompt = afterEntry > 0;
+  const byUuid = new Map<string, TranscriptEntry>();
+  const collected: string[] = [];
   let entryIndex = 0;
   for (const line of lines) {
     const trimmed = line.trim();
@@ -211,26 +201,30 @@ export function extractFinalAssistantMessageAfterEntry(jsonl: string, afterEntry
       continue;
     }
     entryIndex++;
+    if (typeof entry.uuid === "string" && entry.uuid) byUuid.set(entry.uuid, entry);
     if (isSidechainEntry(entry)) continue;
     if (entryIndex <= afterEntry) continue;
-    if (isRealUserPrompt(entry)) {
-      pastLastUserPrompt = true;
-      lastText = "";
-      continue;
-    }
-    if (!pastLastUserPrompt) continue;
+    if (entry.type !== "assistant") continue;
+    if (resolveEntryPromptId(entry, byUuid) !== promptId) continue;
     const text = assistantText(entry);
-    if (text) lastText = text;
+    if (text) collected.push(text);
   }
-  return lastText.trim();
+  return collected.join("\n\n").trim();
 }
 
 /**
- * Extract text from the `last_assistant_message` field in the Stop hook
- * payload. This is the content of the final assistant message — either a plain
- * string or an array of content blocks (same shape as transcript entries).
- * Thinking and tool_use blocks are dropped, matching extractLastAssistantTurn.
+ * Count valid JSON entries in a JSONL string. Used to record the high-water-mark
+ * after a pre-flush so the Stop hook knows where to resume in full-capture mode.
  */
+export function countTranscriptEntries(jsonl: string): number {
+  let count = 0;
+  for (const line of jsonl.split("\n")) {
+    if (!line.trim()) continue;
+    try { JSON.parse(line); count++; } catch {}
+  }
+  return count;
+}
+
 /**
  * Extract the ordered narration, reasoning, and tool steps for the most recent
  * turn (since the last real user prompt). Used by the reasoning tailer to stream

package/runner/src/adapters/codex-agent-message-capture.ts

@@ -4,7 +4,6 @@ type CompleteItemOptions = { includeInResponse?: boolean; phase?: unknown };
 
 const MAX_CAPTURED_RESPONSE_CHARS = 16_000;
 const TRUNCATION_MARKER_PREFIX = "[truncated:";
-const TERSE_FINAL_MAX_CHARS = 280;
 
 export class CodexAgentMessageCapture {
   private segments: ResponseEntry[][] = [];
@@ -46,11 +45,16 @@ export class CodexAgentMessageCapture {
     this.currentSegment = [];
   }
 
+  // Deterministic turn-final response: prefer the trailing structured report span, not a generic
+  // post-handoff coda. The original #1079/#1086 trailing-run rule correctly kept early narration
+  // out, but it over-trimmed Codex turns shaped "summary -> workspace ready -> Landed..." and made
+  // report-up deliver only the coda (#1136). We still drop leading narration; we just let structured
+  // report markers beat a terse final status line.
   finish(emit: EmitAgentMessage): string | undefined {
     this.closeSegment(emit);
-    const selectedSegments = selectResponseSegments(this.segments);
+    const trailingSegment = selectFinalResponseSegments(this.segments);
     this.segments = [];
-    const text = selectedSegments.length ? selectedSegments.map(segmentBody).join("\n\n").trim() : undefined;
+    const text = trailingSegment ? trailingSegment.map(segmentBody).join("\n\n").trim() : undefined;
     return truncateCapturedResponse(text);
   }
 
@@ -96,41 +100,39 @@ export class CodexAgentMessageCapture {
   }
 }
 
-function selectResponseSegments(segments: ResponseEntry[][]): ResponseEntry[][] {
-  const nonEmptySegments = segments.filter((segment) => segment.length > 0);
-  const finalSegment = nonEmptySegments.at(-1);
-  if (!finalSegment) return [];
-  const finalBody = segmentBody(finalSegment);
-  if (!isTerseTerminalStatus(finalBody)) return [finalSegment];
-
-  // Codex often posts the real wrap-up across multiple assistant segments before a
-  // final workspace-ready/status line. Keep contiguous substantive segments after
-  // the last procedural assistant segment, then append the terminal status.
-  const selectedSegments: ResponseEntry[][] = [];
-  for (let index = nonEmptySegments.length - 2; index >= 0; index -= 1) {
-    const candidate = nonEmptySegments[index];
-    if (!candidate || !isSubstantiveResponseSegment(segmentBody(candidate))) break;
-    selectedSegments.unshift(candidate);
+function segmentBody(segment: ResponseEntry[]): string {
+  return segment.map((entry) => entry.body).join("\n\n").trim();
+}
+
+function selectFinalResponseSegments(segments: ResponseEntry[][]): ResponseEntry[][] | undefined {
+  const bodies = segments.map(segmentBody).filter(Boolean);
+  if (!bodies.length) return undefined;
+  let end = bodies.length - 1;
+  while (end > 0 && isGenericFinalCoda(bodies[end]!) && bodies.slice(0, end).some(isSubstantiveReportSegment)) end--;
+  const firstReport = bodies.slice(0, end + 1).findIndex(isReportBoundarySegment);
+  if (firstReport >= 0) return segments.slice(firstReport, end + 1);
+  for (let i = end; i >= 0; i--) {
+    if (isSubstantiveReportSegment(bodies[i]!)) return [segments[i]!];
   }
-  return [...selectedSegments, finalSegment];
+  return [segments[end]!];
 }
 
-function segmentBody(segment: ResponseEntry[]): string {
-  return segment.map((entry) => entry.body).join("\n\n").trim();
+const REPORT_BOUNDARY = /(^|\n)(#{1,6}\s|\*\*(summary|what changed|rca|fix|tests?|gates?|verification|risk)\b|(?:summary|what changed|rca|fix|tests?|gates?|verification|risk):)/i;
+const REPORT_STRUCTURE = /(^|\n)\s*[-*]\s+\S|`[^`]+`|\b(typecheck|bun test|tests? pass(?:ed)?|gates? green|rca|verified|implemented)\b/i;
+const GENERIC_FINAL_CODA = /^(?:done|landed(?: on main)?|committed|merged|ready|no further action|nothing further|all set)\b|(?:\bno further action needed\b|\bnothing further needed\b)$/i;
+
+function isReportBoundarySegment(body: string): boolean {
+  return REPORT_BOUNDARY.test(body.trim());
 }
 
-function isTerseTerminalStatus(body: string): boolean {
-  if (body.length > TERSE_FINAL_MAX_CHARS) return false;
-  if (/\n\s*(?:[-*]|\d+\.)\s+/.test(body)) return false;
-  return /\b(?:landed|ready for review|handed off|no further action|done|complete|completed|committed|merged)\b/i.test(body);
+function isSubstantiveReportSegment(body: string): boolean {
+  const trimmed = body.trim();
+  return !isGenericFinalCoda(trimmed) && (trimmed.length >= 120 || isReportBoundarySegment(trimmed) || REPORT_STRUCTURE.test(trimmed));
 }
 
-function isSubstantiveResponseSegment(body: string): boolean {
-  if (body.length >= 120) return true;
-  if (/\n\s*(?:[-*]|\d+\.)\s+/.test(body)) return true;
-  if (/\*\*(?:what changed|changes?|tests?|gates?|verification|risks?|residual risk|summary)\b/i.test(body)) return true;
-  if (/^#{1,3}\s+\S/m.test(body)) return true;
-  return body.split(/\n{2,}/).length >= 2;
+function isGenericFinalCoda(body: string): boolean {
+  const trimmed = body.trim();
+  return trimmed.length <= 180 && GENERIC_FINAL_CODA.test(trimmed) && !isReportBoundarySegment(trimmed);
 }
 
 function truncateCapturedResponse(text: string | undefined): string | undefined {

package/runner/src/adapters/codex.ts

@@ -1,7 +1,7 @@
 import { accessSync, constants, existsSync, readFileSync, realpathSync, readdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, join, resolve } from "node:path";
-import type { ContextState, InteractivePrompt, LivenessSignal, Message, ProviderState } from "agent-relay-sdk";
+import type { ContextState, InteractivePrompt, LivenessSignal, Message, MessageTurnEndReason, ProviderState } from "agent-relay-sdk";
 import { isRecord, stringValue } from "agent-relay-sdk";
 import { isPidAlive, killPid, processTreePids, processTreePidsFromTable, waitForPidsExit } from "agent-relay-sdk/process-utils";
 import { profileAllowsRelayFeature, providerMessageText, relayContext, type ManagedProcess, type ProviderAdapter, type ProviderConfig, type ProviderPermissionDecisionInput, type ProviderSessionEvent, type ProviderStatusUpdate, type RunnerSpawnConfig, type SpawnArgs, type TerminalAttachSpec } from "../adapter";
@@ -144,13 +144,13 @@ export class CodexAdapter implements ProviderAdapter {
       const turnStatus = isRecord(activeTurn) ? stringValue(activeTurn.status) : undefined;
       if (turnStatus === "inProgress") return "busy";
       if (turnStatus === "completed" || turnStatus === "interrupted" || turnStatus === "failed") {
-        this.finishMainTurn();
+        this.finishMainTurn(codexEndedByFrom(turnStatus));
         return "idle";
       }
       const threadStatus = statusType(thread?.status);
       if (threadStatus === "active") return "busy";
       if (threadStatus === "idle" || threadStatus === "notLoaded" || threadStatus === "systemError") {
-        this.finishMainTurn();
+        this.finishMainTurn(codexEndedByFrom(threadStatus));
         return "idle";
       }
     } catch {
@@ -508,7 +508,7 @@ export class CodexAdapter implements ProviderAdapter {
       if (threadId && this.subagentThreads.has(threadId)) {
         this.statusCb({ status: "idle", reason: "subagent", id: threadId, ...this.subagentThreads.get(threadId) });
       } else {
-        this.finishMainTurn();
+        this.finishMainTurn(codexEndedByFrom(method));
       }
     }
     if ((method.includes("thread/compacted") || method.includes("thread.compacted")) && threadId) {
@@ -527,15 +527,16 @@ export class CodexAdapter implements ProviderAdapter {
         if (status === "idle" || status === "notLoaded") this.statusCb({ status: "idle", reason: "subagent", id: threadId, ...this.subagentThreads.get(threadId) });
       } else {
         if (status === "active") this.statusCb({ status: "busy", reason: "provider-turn", providerState: this.providerStateFromThreadStatus(params?.status, params) });
-        if (status === "idle" || status === "notLoaded" || status === "systemError") this.finishMainTurn();
+        if (status === "idle" || status === "notLoaded" || status === "systemError") this.finishMainTurn(codexEndedByFrom(status));
       }
     }
   }
 
   // Turn one completed Codex thread item into a session-mirror event. agentMessage text is
-  // mirrored as narration as it lands; the captured turn-final response repeats the substantive
-  // assistant answer, including a substantive wrap-up segment before a terse terminal status.
-  // The rest (user prompt echo, reasoning, tool steps) is surfaced as it lands.
+  // mirrored as narration as it lands; the captured turn-final response repeats only the
+  // TRAILING agentMessage run — the segment after the last tool/file-change/reasoning
+  // boundary (design #1079 §3.2) — never earlier mid-work narration, which was already
+  // mirrored live. The rest (user prompt echo, reasoning, tool steps) is surfaced as it lands.
   private handleCodexItem(item: Record<string, unknown> | undefined): void {
     if (!item) return;
     const type = stringValue(item.type);
@@ -676,14 +677,23 @@ export class CodexAdapter implements ProviderAdapter {
     if (method.includes("outputDelta") || method.includes("output_delta") || method.includes("progress")) return;
   }
 
-  private flushTurnResponse(): void {
+  // A turn-final capture is emitted ONLY for a genuine `completed` turn (design #1079 §3.2):
+  // failed/interrupted turns must never produce a turn-final. Every "response"-type
+  // ProviderSessionEvent is unconditionally dual-stamped turnFinal/final downstream
+  // (publishCapturedResponse's provider-agnostic stamp), so the only way to keep a
+  // failed/interrupted partial OUT of D's work-final ring is to never emit it as a
+  // "response" event at all (#1083 Finding 1). The partial text was already mirrored live
+  // as narration by the `emit` callback inside agentMessageCapture.finish(), so it's still
+  // visible in the dashboard.
+  private flushTurnResponse(endedBy: MessageTurnEndReason): void {
     const text = this.agentMessageCapture.finish((body) => this.emitAgentNarration(body));
-    if (text) this.sessionEventCb({ type: "response", origin: "provider", body: text, final: true, ...(this.activeTurnId ? { turnId: this.activeTurnId } : {}) });
+    if (!text || endedBy !== "completed") return;
+    this.sessionEventCb({ type: "response", origin: "provider", body: text, final: true, confidence: "definitive", endedBy, ...(this.activeTurnId ? { turnId: this.activeTurnId } : {}) });
   }
 
-  private finishMainTurn(): void {
+  private finishMainTurn(endedBy: MessageTurnEndReason): void {
     this.flushBufferedReasoning(); // surface any trailing reasoning before the closing response
-    this.flushTurnResponse();
+    this.flushTurnResponse(endedBy);
     const turnId = this.activeTurnId;
     this.activeTurnId = undefined;
     this.pendingApprovals.clear();
@@ -1151,6 +1161,14 @@ function statusType(value: unknown): string | undefined {
   return isRecord(value) ? stringValue(value.type) : undefined;
 }
 
+// Maps any Codex turn-ending signal — a turn/failed|interrupted (dot-notation too) app-server
+// method name, a turn status ("completed"/"interrupted"/"failed"), or a thread status
+// ("idle"/"notLoaded"/"systemError") — to the Part A (#1082) turn-end reason. "completed" is
+// the default for every signal that isn't explicitly a failure or an interruption.
+function codexEndedByFrom(value: string | undefined): MessageTurnEndReason {
+  return value === "systemError" || value?.includes("failed") ? "failed" : value?.includes("interrupted") ? "interrupted" : "completed";
+}
+
 function activeFlags(value: unknown): string[] {
   if (!isRecord(value) || !Array.isArray(value.activeFlags)) return [];
   return value.activeFlags.filter((flag): flag is string => typeof flag === "string" && flag.length > 0);

package/runner/src/control-server.ts

@@ -49,12 +49,15 @@ interface ControlServerOptions {
   // dashboard chat without the agent re-emitting it via /reply.
   // isPreFlush: true signals a mid-turn call from a PreToolUse hook — flush any
   // un-mirrored narrative before the interactive form appears in chat (#435).
-  onSessionTurn?(input: { transcriptPath: string; lastAssistantMessage?: unknown; isPreFlush?: boolean }): Promise<void>;
+  // promptId (#1086): Claude's native `prompt_id` from the Stop hook payload — the
+  // stable, provider-native turn identifier used instead of a minted random UUID.
+  onSessionTurn?(input: { transcriptPath: string; lastAssistantMessage?: unknown; promptId?: string; isPreFlush?: boolean }): Promise<void>;
   onPermissionResolved?(input: ResolvedPermissionPrompt): Promise<void> | void;
   // A provider UserPromptSubmit hook hands over the prompt the human typed
   // directly into the session (web terminal / TUI) so the runner can mirror it
   // into the dashboard chat and start tailing the turn transcript for reasoning.
-  onUserPrompt?(input: { prompt: string; transcriptPath?: string }): Promise<void>;
+  // promptId (#1086): Claude's native `prompt_id` for the turn this prompt starts.
+  onUserPrompt?(input: { prompt: string; transcriptPath?: string; promptId?: string }): Promise<void>;
   // A provider session-boundary hook (Claude PreCompact / SessionEnd) signals an imminent
   // context reset or termination so the runner can run end-of-session work (#183 pre-destroy
   // seam: #184 context-ratio capture) before the invasive operation. `reason` is the raw
@@ -501,6 +504,7 @@ async function handleSessionTurn(req: Request, options: ControlServerOptions): P
   const body = await req.json().catch(() => null);
   const transcriptPath = isRecord(body) && typeof body.transcriptPath === "string" ? body.transcriptPath : "";
   const lastAssistantMessage = isRecord(body) ? body.lastAssistantMessage : undefined;
+  const promptId = isRecord(body) && typeof body.promptId === "string" && body.promptId ? body.promptId : 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).
@@ -511,7 +515,7 @@ async function handleSessionTurn(req: Request, options: ControlServerOptions): P
   // reply-obligation check, so the captured turn must be persisted (and the
   // obligation cleared) before this response returns.
   try {
-    await options.onSessionTurn({ transcriptPath, lastAssistantMessage });
+    await options.onSessionTurn({ transcriptPath, lastAssistantMessage, ...(promptId ? { promptId } : {}) });
     return Response.json({ ok: true });
   } catch (error) {
     return Response.json({ ok: false, reason: errMessage(error) }, { status: 500 });
@@ -524,8 +528,9 @@ async function handleUserPrompt(req: Request, options: ControlServerOptions): Pr
   const prompt = isRecord(body) && typeof body.prompt === "string" ? body.prompt : "";
   if (!prompt.trim()) return Response.json({ ok: false, reason: "prompt required" }, { status: 400 });
   const transcriptPath = isRecord(body) && typeof body.transcriptPath === "string" ? body.transcriptPath : undefined;
+  const promptId = isRecord(body) && typeof body.promptId === "string" && body.promptId ? body.promptId : undefined;
   // Fire-and-forget: the hook must not block Claude's turn on relay round-trips.
-  void Promise.resolve(options.onUserPrompt({ prompt, transcriptPath })).catch(() => {});
+  void Promise.resolve(options.onUserPrompt({ prompt, transcriptPath, ...(promptId ? { promptId } : {}) })).catch(() => {});
   return Response.json({ ok: true });
 }
 

package/runner/src/response-capture-report.ts

@@ -12,8 +12,11 @@ type SessionPublisher = (input: {
   replyTo?: number;
 }) => void | Promise<void>;
 
+// #1086: dual-stamp the Part A (#1082) turn-finality field alongside the legacy
+// `final` alias so old consumers keep working while new ones can key off the
+// typed `turnFinal` flag directly instead of every writer's own `final: true`.
 function finalSession(session: MessageSessionMeta): MessageSessionMeta {
-  return { ...session, final: true };
+  return { ...session, turnFinal: true, final: true };
 }
 
 export async function publishCapturedResponse(input: {