fix: enforce user message ordering before agent responses in turns

Author: jacobjmc

docs/app-server-events.md

@@ -55,6 +55,33 @@ OpenCode has no native turn lifecycle notifications. The backend emits:
 - `turn/completed` after a successful prompt response
 - `error` for failed prompt paths (instead of emitting `turn/completed`)
 
+## Message Ordering Invariant
+
+Within a conversation thread, items MUST be displayed in semantic order:
+
+1. **Turn Structure**: A turn consists of a user message followed by zero or more
+   agent responses (messages, tool calls, reasoning, etc.)
+
+2. **Ordering Rule**: Within each turn, the user message MUST appear before any
+   agent responses, regardless of the item ID sequence numbers.
+
+3. **Cross-Turn Order**: Turns are ordered by the user message's sequence number.
+
+### Why This Matters
+
+The backend assigns item IDs (`item_1`, `item_2`, ...) in event processing order,
+not semantic order. Race conditions can cause tool events to be processed before
+user message events, resulting in tool IDs < user message IDs.
+
+### Enforcement (Defense in Depth)
+
+- **Backend**: Pre-allocates user message ID at turn start to ensure it's always
+  lowest in the turn (`event_translator.rs:start_turn`)
+- **Frontend**: Enforces semantic ordering in `sortItemsBySyntheticOrder()` 
+  regardless of ID sequence (`threadItems.ts`)
+
+Both layers enforce the invariant so a regression in one doesn't break ordering.
+
 ## Notes
 
 - All protocol translation stays in Rust by design.

src-tauri/src/backend/event_translator.rs

@@ -119,9 +119,12 @@ impl SessionTranslationState {
     }
 
     /// Start a new turn for a specific session.
+    ///
+    /// INVARIANT: User message ID is always lowest in a turn. If not already set,
+    /// we pre-allocate it here so any subsequent tool IDs are guaranteed higher.
     pub(crate) fn start_turn(&mut self, session_id: String, turn_id: String) {
         self.session_id = session_id.clone();
-        let turn_state = self.session_turns.entry(session_id).or_default();
+        let turn_state = self.session_turns.entry(session_id.clone()).or_default();
         // User prompt parts can arrive before `session.status=active` (common for
         // subagent sessions). Preserve the in-progress user message so later chunks
         // keep merging into the same frontend item instead of creating a duplicate.
@@ -135,8 +138,19 @@ impl SessionTranslationState {
         turn_state.reasoning_item_id = None;
         turn_state.reasoning_part_id = None;
         turn_state.reasoning_text_len = 0;
-        turn_state.user_message_item_id = preserved_user_message_item_id;
-        turn_state.user_message_text = preserved_user_message_text;
+
+        // INVARIANT: Pre-allocate user message ID if not already set.
+        // This ensures user message ID is always lower than any tool IDs in this turn.
+        if let Some(id) = preserved_user_message_item_id {
+            let turn_state = self.session_turns.get_mut(&session_id).unwrap();
+            turn_state.user_message_item_id = Some(id);
+            turn_state.user_message_text = preserved_user_message_text;
+        } else {
+            let pre_allocated_id = self.next_item_id();
+            let turn_state = self.session_turns.get_mut(&session_id).unwrap();
+            turn_state.user_message_item_id = Some(pre_allocated_id);
+            turn_state.user_message_text = String::new();
+        }
     }
 
     /// Prepare translation state for replaying historical messages.
@@ -2942,6 +2956,68 @@ mod tests {
         );
     }
 
+    #[test]
+    fn user_message_id_always_lower_than_tool_ids_in_turn() {
+        let mut state = SessionTranslationState::new("ses_test".into());
+
+        // Simulate turn starting with session.status=active
+        state.start_turn("ses_test".into(), "turn_1".into());
+
+        // Get user message ID (should be pre-allocated by start_turn)
+        let user_id = state.user_message_item("ses_test");
+
+        // Simulate tool calls getting IDs
+        let tool_id_1 = state.next_item_id();
+        let tool_id_2 = state.next_item_id();
+
+        // Parse sequence numbers
+        let user_seq: u64 = user_id.strip_prefix("item_").unwrap().parse().unwrap();
+        let tool_seq_1: u64 = tool_id_1.strip_prefix("item_").unwrap().parse().unwrap();
+        let tool_seq_2: u64 = tool_id_2.strip_prefix("item_").unwrap().parse().unwrap();
+
+        assert!(
+            user_seq < tool_seq_1,
+            "User message ID ({user_id}) must be lower than first tool ID ({tool_id_1})"
+        );
+        assert!(
+            user_seq < tool_seq_2,
+            "User message ID ({user_id}) must be lower than second tool ID ({tool_id_2})"
+        );
+    }
+
+    #[test]
+    fn start_turn_preserves_existing_user_message_id() {
+        let mut state = SessionTranslationState::new("ses_test".into());
+
+        // Simulate user message arriving BEFORE session.status=active
+        let early_user_id = state.user_message_item("ses_test");
+
+        // Now turn starts - should preserve the existing user message ID
+        state.start_turn("ses_test".into(), "turn_1".into());
+
+        // Get user message ID again - should be the same
+        let after_start_id = state.user_message_item("ses_test");
+
+        assert_eq!(
+            early_user_id, after_start_id,
+            "start_turn must preserve existing user message ID"
+        );
+
+        // Tool IDs should still be higher
+        let tool_id = state.next_item_id();
+        let user_seq: u64 = early_user_id
+            .strip_prefix("item_")
+            .unwrap()
+            .parse()
+            .unwrap();
+        let tool_seq: u64 = tool_id.strip_prefix("item_").unwrap().parse().unwrap();
+
+        assert!(
+            user_seq < tool_seq,
+            "User message ID ({early_user_id}) must be lower than tool ID ({tool_id})"
+        );
+    }
+
     #[test]
     fn part_delta_routes_reasoning_by_part_id() {
         let mut state = make_state();

src-tauri/src/shared/codex_core.rs

@@ -2135,6 +2135,7 @@ mod tests {
                 "hello".to_string(),
                 Some(vec!["http://localhost/image.png".to_string()]),
                 None,
+                None,
             )
             .await;
 

src/utils/threadItems.test.ts

@@ -145,6 +145,124 @@ describe("threadItems", () => {
     ]);
   });
 
+  it("places user message before agent responses even when user has higher ID", () => {
+    // BUG CASE: backend assigned tool ID before user message ID
+    const items: ConversationItem[] = [
+      {
+        id: "item_1",
+        kind: "tool",
+        toolType: "fileChange",
+        title: "Edit: App.tsx",
+        detail: "",
+        status: "completed",
+      },
+      {
+        id: "item_2",
+        kind: "message",
+        role: "user",
+        text: "Find where skills is passed to Composer",
+      },
+      {
+        id: "item_3",
+        kind: "message",
+        role: "assistant",
+        text: "Let me search for that...",
+      },
+    ];
+
+    const prepared = prepareThreadItems(items);
+
+    // INVARIANT: User message must appear before agent responses
+    expect(prepared[0].kind).toBe("message");
+    expect((prepared[0] as { role: string }).role).toBe("user");
+    expect(prepared.map((item) => item.id)).toEqual(["item_2", "item_1", "item_3"]);
+  });
+
+  it("handles multiple turns with out-of-order IDs", () => {
+    const items: ConversationItem[] = [
+      // Turn 1: tool arrived before user message
+      {
+        id: "item_1",
+        kind: "tool",
+        toolType: "read",
+        title: "Read foo.ts",
+        detail: "",
+        status: "completed",
+      },
+      {
+        id: "item_2",
+        kind: "message",
+        role: "user",
+        text: "First prompt",
+      },
+      {
+        id: "item_3",
+        kind: "message",
+        role: "assistant",
+        text: "First response",
+      },
+      // Turn 2: correct order
+      {
+        id: "item_4",
+        kind: "message",
+        role: "user",
+        text: "Second prompt",
+      },
+      {
+        id: "item_5",
+        kind: "tool",
+        toolType: "write",
+        title: "Write bar.ts",
+        detail: "",
+        status: "completed",
+      },
+    ];
+
+    const prepared = prepareThreadItems(items);
+
+    // Turn 1: user message should be first
+    expect(prepared[0].id).toBe("item_2"); // user
+    expect(prepared[1].id).toBe("item_1"); // tool (moved after user)
+    expect(prepared[2].id).toBe("item_3"); // assistant
+    // Turn 2: already correct
+    expect(prepared[3].id).toBe("item_4"); // user
+    expect(prepared[4].id).toBe("item_5"); // tool
+  });
+
+  it("handles user message with multiple preceding tool items", () => {
+    const items: ConversationItem[] = [
+      {
+        id: "item_1",
+        kind: "tool",
+        toolType: "read",
+        title: "Read file1.ts",
+        detail: "",
+        status: "completed",
+      },
+      {
+        id: "item_2",
+        kind: "tool",
+        toolType: "read",
+        title: "Read file2.ts",
+        detail: "",
+        status: "completed",
+      },
+      {
+        id: "item_3",
+        kind: "message",
+        role: "user",
+        text: "User prompt",
+      },
+    ];
+
+    const prepared = prepareThreadItems(items);
+
+    // User message should be first, followed by both tools
+    expect(prepared[0].id).toBe("item_3"); // user
+    expect(prepared[1].id).toBe("item_1"); // tool
+    expect(prepared[2].id).toBe("item_2"); // tool
+  });
+
   it("summarizes explored reads and hides raw commands", () => {
     const items: ConversationItem[] = [
       {

src/utils/threadItems.ts

@@ -456,22 +456,92 @@ function getSyntheticItemOrderKey(id: string): SyntheticItemOrderKey | null {
   };
 }
 
+type IndexedItem = {
+  item: ConversationItem;
+  index: number;
+  key: SyntheticItemOrderKey | null;
+  isUserMessage: boolean;
+  isAssistantMessage: boolean;
+  isToolItem: boolean;
+};
+
+/**
+ * INVARIANT: User messages appear before agent responses within the same turn.
+ *
+ * This function enforces semantic ordering regardless of ID assignment order.
+ * The backend may assign IDs in processing order (tool gets ID before user message),
+ * but the UI must display user message first.
+ */
 function sortItemsBySyntheticOrder(items: ConversationItem[]) {
   if (items.length < 2) {
     return items;
   }
-  const withIndex = items.map((item, index) => ({
+
+  const indexed: IndexedItem[] = items.map((item, index) => ({
     item,
     index,
     key: getSyntheticItemOrderKey(item.id),
+    isUserMessage: item.kind === "message" && item.role === "user",
+    isAssistantMessage: item.kind === "message" && item.role === "assistant",
+    isToolItem: item.kind === "tool" || item.kind === "explore",
   }));
-  withIndex.sort((a, b) => {
+
+  // First pass: sort by ID sequence within same family
+  indexed.sort((a, b) => {
     if (a.key && b.key && a.key.family === b.key.family && a.key.seq !== b.key.seq) {
       return a.key.seq - b.key.seq;
     }
     return a.index - b.index;
   });
-  return withIndex.map((entry) => entry.item);
+
+  // Second pass: enforce user-message-first invariant
+  // For each user message, move it before any UNOWNED tool items that precede it.
+  // A tool is "unowned" if there's no user message between it and the current user.
+  // Stop at any message (user or assistant) - they mark turn boundaries.
+  const result: IndexedItem[] = [];
+  const maxTurnWindow = 20;
+
+  for (let i = 0; i < indexed.length; i++) {
+    const current = indexed[i];
+
+    if (current.isUserMessage && current.key) {
+      const userSeq = current.key.seq;
+      const family = current.key.family;
+
+      // Find insertion point: before preceding unowned tool items
+      let insertAt = result.length;
+      let foundOwnedTools = false;
+
+      for (let j = result.length - 1; j >= 0; j--) {
+        const prev = result[j];
+        if (!prev.key || prev.key.family !== family) break;
+        // Any message marks turn boundary - tools before it belong to that turn
+        if (prev.isUserMessage || prev.isAssistantMessage) {
+          foundOwnedTools = true;
+          break;
+        }
+        // Only move tool/explore items, not reasoning/diff/review/todo
+        if (!prev.isToolItem) break;
+        // Tool item with lower seq - check if same turn
+        if (prev.key.seq < userSeq && userSeq - prev.key.seq <= maxTurnWindow) {
+          insertAt = j;
+        } else {
+          break;
+        }
+      }
+
+      // Only move if the tools are unowned (no prior message claimed them)
+      if (foundOwnedTools) {
+        insertAt = result.length;
+      }
+
+      result.splice(insertAt, 0, current);
+    } else {
+      result.push(current);
+    }
+  }
+
+  return result.map((entry) => entry.item);
 }
 
 export function prepareThreadItems(items: ConversationItem[]) {