fix(acp): stabilize streaming timeline UI and stopReason handling

Author: bajrangCoder

src/lib/acp/client.ts

@@ -326,7 +326,7 @@ export class ACPClient {
 				}),
 			);
 
-			this._session.finishAgentTurn();
+			this._session.finishAgentTurn(result.stopReason);
 			return result;
 		} catch (error) {
 			this._session.finishAgentTurn();

src/lib/acp/history.ts

@@ -1,5 +1,17 @@
 const STORAGE_KEY = "acpSessionHistory";
 const MAX_ENTRIES = 30;
+const VALID_STOP_REASONS = new Set([
+	"end_turn",
+	"max_tokens",
+	"max_turn_requests",
+	"refusal",
+	"cancelled",
+]);
+
+export interface ACPHistoryTurnStop {
+	stopReason: string;
+	timestamp: number;
+}
 
 export interface ACPHistoryEntry {
 	sessionId: string;
@@ -8,6 +20,7 @@ export interface ACPHistoryEntry {
 	agentName: string;
 	title: string;
 	preview: string;
+	turnStops: ACPHistoryTurnStop[];
 	createdAt: string;
 	updatedAt: string;
 }
@@ -27,6 +40,24 @@ type ACPHistorySaveInput = Partial<ACPHistoryEntry> &
 function normalizeEntry(entry: Partial<ACPHistoryEntry> = {}): ACPHistoryEntry {
 	const createdAt = entry.createdAt || new Date().toISOString();
 	const updatedAt = entry.updatedAt || createdAt;
+	const turnStops = Array.isArray(entry.turnStops)
+		? entry.turnStops
+				.map((item) => {
+					const stopReason =
+						typeof item?.stopReason === "string" ? item.stopReason.trim() : "";
+					if (!VALID_STOP_REASONS.has(stopReason)) return null;
+
+					const timestamp = Number.isFinite(item?.timestamp)
+						? Number(item.timestamp)
+						: Date.now();
+
+					return {
+						stopReason,
+						timestamp,
+					};
+				})
+				.filter((item): item is ACPHistoryTurnStop => Boolean(item))
+		: [];
 
 	return {
 		sessionId:
@@ -37,6 +68,7 @@ function normalizeEntry(entry: Partial<ACPHistoryEntry> = {}): ACPHistoryEntry {
 			typeof entry.agentName === "string" ? entry.agentName.trim() : "",
 		title: typeof entry.title === "string" ? entry.title.trim() : "",
 		preview: typeof entry.preview === "string" ? entry.preview.trim() : "",
+		turnStops,
 		createdAt,
 		updatedAt,
 	};
@@ -100,6 +132,10 @@ const acpHistory = {
 				agentName: normalized.agentName || current.agentName,
 				title: normalized.title || current.title,
 				preview: normalized.preview || current.preview,
+				turnStops:
+					normalized.turnStops.length > 0
+						? normalized.turnStops
+						: current.turnStops,
 				createdAt: current.createdAt,
 				updatedAt: normalized.updatedAt || new Date().toISOString(),
 			};

src/lib/acp/models.ts

@@ -1,5 +1,6 @@
 import type {
 	Plan as ACPPlan,
+	StopReason as ACPStopReason,
 	ToolCall as ACPToolCall,
 	ContentBlock,
 	PlanEntry,
@@ -40,13 +41,22 @@ export const ConnectionState = {
 	ERROR: "error",
 } as const;
 
+export const StopReason = {
+	END_TURN: "end_turn",
+	MAX_TOKENS: "max_tokens",
+	MAX_TURN_REQUESTS: "max_turn_requests",
+	REFUSAL: "refusal",
+	CANCELLED: "cancelled",
+} as const;
+
 export type ToolCallStatus =
 	(typeof ToolCallStatus)[keyof typeof ToolCallStatus];
 export type ToolKind = (typeof ToolKind)[keyof typeof ToolKind];
 export type PlanEntryStatus =
 	(typeof PlanEntryStatus)[keyof typeof PlanEntryStatus];
 export type ConnectionState =
 	(typeof ConnectionState)[keyof typeof ConnectionState];
+export type StopReason = ACPStopReason;
 
 export interface ToolCall extends ACPToolCall {
 	timestamp?: number;
@@ -66,6 +76,11 @@ export interface ChatMessage {
 	streaming?: boolean;
 }
 
+export interface TurnStop {
+	stopReason: StopReason;
+	timestamp: number;
+}
+
 export type TimelineEntry =
 	| {
 			entryId: string;
@@ -81,4 +96,9 @@ export type TimelineEntry =
 			entryId: string;
 			type: "plan";
 			plan: Plan;
+	  }
+	| {
+			entryId: string;
+			type: "turn_stop";
+			turnStop: TurnStop;
 	  };

src/lib/acp/session.ts

@@ -7,10 +7,16 @@ import type {
 	ChatMessage,
 	Plan,
 	PlanEntry,
+	StopReason,
 	TimelineEntry,
 	ToolCall,
+	TurnStop,
 } from "./models";
-import { ToolCallStatus } from "./models";
+import { StopReason as StopReasons, ToolCallStatus } from "./models";
+
+const STOP_REASON_VALUES = new Set<StopReason>(
+	Object.values(StopReasons) as StopReason[],
+);
 
 type SessionEventType =
 	| "message_update"
@@ -29,6 +35,7 @@ export class ACPSession {
 	readonly messages: ChatMessage[] = [];
 	readonly timeline: TimelineEntry[] = [];
 	readonly toolCalls: Map<string, ToolCall> = new Map();
+	readonly turnStops: TurnStop[] = [];
 	plan: Plan | null = null;
 	title: string | null = null;
 	updatedAt: string | null = null;
@@ -128,18 +135,48 @@ export class ACPSession {
 		return this.pendingPermissions.shift();
 	}
 
-	finishAgentTurn(): void {
+	finishAgentTurn(stopReason?: StopReason | null): void {
 		this.closeCurrentAgentMessage();
 		this.closeCurrentThoughtMessage();
 		this.closeCurrentUserMessage();
 		this.currentPlanEntryId = null;
+		const normalizedStopReason = this.normalizeStopReason(stopReason);
+		if (this.shouldPersistStopReason(normalizedStopReason)) {
+			this.appendTurnStop(normalizedStopReason);
+		}
 		this.emit("session_end", null);
 	}
 
 	getToolCall(toolCallId: string): ToolCall | undefined {
 		return this.toolCalls.get(toolCallId);
 	}
 
+	setPersistedTurnStops(turnStops: TurnStop[]): void {
+		for (let index = this.timeline.length - 1; index >= 0; index--) {
+			if (this.timeline[index]?.type === "turn_stop") {
+				this.timeline.splice(index, 1);
+			}
+		}
+		this.turnStops.length = 0;
+
+		const normalizedStops = Array.isArray(turnStops)
+			? turnStops
+					.map((entry) => {
+						const stopReason = this.normalizeStopReason(entry?.stopReason);
+						if (!this.shouldPersistStopReason(stopReason)) return null;
+						const timestamp = Number.isFinite(entry?.timestamp)
+							? Number(entry.timestamp)
+							: Date.now();
+						return { stopReason, timestamp };
+					})
+					.filter((entry): entry is TurnStop => Boolean(entry))
+			: [];
+
+		normalizedStops.forEach((entry) => {
+			this.appendTurnStop(entry.stopReason, entry.timestamp);
+		});
+	}
+
 	private handleMessageChunk(
 		role: ChatMessage["role"],
 		content: ContentBlock,
@@ -313,6 +350,35 @@ export class ACPSession {
 		this.emit("timeline_update", entry);
 	}
 
+	private appendTurnStop(
+		stopReason: StopReason,
+		timestamp: number = Date.now(),
+	): void {
+		const turnStop: TurnStop = {
+			stopReason,
+			timestamp,
+		};
+		this.turnStops.push(turnStop);
+		this.pushTimelineEntry({
+			entryId: this.nextTimelineId(),
+			type: "turn_stop",
+			turnStop,
+		});
+	}
+
+	private normalizeStopReason(value: unknown): StopReason | null {
+		if (typeof value !== "string") return null;
+		if (!STOP_REASON_VALUES.has(value as StopReason)) return null;
+		return value as StopReason;
+	}
+
+	private shouldPersistStopReason(
+		stopReason: StopReason | null,
+	): stopReason is StopReason {
+		if (!stopReason) return false;
+		return stopReason !== StopReasons.END_TURN;
+	}
+
 	private createMessage(
 		role: ChatMessage["role"],
 		content: ContentBlock[] = [],
@@ -415,5 +481,6 @@ export class ACPSession {
 		this.agentTextBuffer = "";
 		this.thoughtTextBuffer = "";
 		this.userTextBuffer = "";
+		this.turnStops.length = 0;
 	}
 }