fix(ai): align backend event names and payloads with frontend listeners

Fix critical event name mismatch in the legacy AI streaming pipeline where
the Rust backend emitted "ai:stream" but all frontend listeners expected
"ai:stream_chunk". Also flatten StreamEventPayload from nested
{ thread_id, chunk: StreamChunk } to flat { thread_id, content, done }
matching the frontend StreamChunkEvent interface.

Backend changes (src-tauri/src/ai/mod.rs):
- Rename event "ai:stream" to "ai:stream_chunk"
- Flatten StreamEventPayload to { thread_id, content, done }
- Add ToolCallPayload struct and "ai:tool_call" event emission when
  streaming chunks contain tool calls (previously silently dropped)
- Add doc comments documenting event name, payload, and listeners

Test fixes (src/context/__tests__/AIContext.test.tsx):
- Fix hyphenated event names to match actual underscore-based names:
  ai:stream-start → ai:stream_chunk, ai:stream-chunk → ai:tool_call,
  ai:stream-end → ai:tool_result, ai:stream-error → ai:error

Event contract documentation:
- protocol.rs: Document WsMessage as the "cortex-event" payload contract
- events.ts: Add module-level docs explaining two AI pipelines, add
  per-interface Tauri event annotations with emitter and pipeline info
- AIStreamContext.tsx: Document all 4 consumed legacy pipeline events
- SDKContext.tsx: Annotate "cortex-event" listener with contract details
- docs/AI_EVENT_CONTRACTS.md: New 190-line comprehensive reference for
  all AI event channels, both pipelines, payload shapes, and wiring

Author: echobt

docs/AI_EVENT_CONTRACTS.md

@@ -0,0 +1,190 @@
+# AI Event Contracts
+
+This document describes all Tauri IPC event channels used for AI features in Cortex Desktop, their payload shapes, emitters, and listeners.
+
+## Overview
+
+Cortex Desktop has **two separate AI event pipelines**:
+
+| Pipeline | Tauri Event | Purpose | Status |
+|----------|-------------|---------|--------|
+| **Cortex Protocol** | `"cortex-event"` | Primary agent pipeline (sessions, streaming, tools, approvals) | Active / Primary |
+| **Legacy AI Module** | `"ai:stream_chunk"`, `"ai:tool_call"`, etc. | Direct model streaming, inline completions | Active / Secondary |
+
+---
+
+## Pipeline 1: Cortex Protocol (`"cortex-event"`)
+
+### Channel
+
+- **Tauri Event:** `"cortex-event"`
+- **Emitter:** `src-tauri/src/ai/session.rs` → `convert_event_to_ws()`
+- **Payload Type:** `WsMessage` enum (see `src-tauri/src/ai/protocol.rs`)
+- **Serialization:** `#[serde(tag = "type", rename_all = "snake_case")]`
+
+### Frontend Listeners
+
+| File | Hook/Method |
+|------|-------------|
+| `src/context/SDKContext.tsx` | `useTauriListen<CortexEvent>("cortex-event", ...)` |
+| `src/context/AgentFollowContext.tsx` | `listen("cortex-event", ...)` |
+
+### Message Types
+
+All messages are JSON objects with a `type` field discriminator:
+
+#### Streaming
+
+| `type` | Fields | Description |
+|--------|--------|-------------|
+| `stream_chunk` | `{ content: string }` | Streaming text delta |
+| `agent_message` | `{ content: string }` | Full message (end of stream) |
+| `reasoning_delta` | `{ delta: string }` | Thinking/reasoning text delta |
+
+#### Tool Execution
+
+| `type` | Fields | Description |
+|--------|--------|-------------|
+| `tool_call_begin` | `{ call_id, tool_name, arguments }` | Tool execution started |
+| `tool_call_output_delta` | `{ call_id, stream, chunk }` | Tool stdout/stderr (base64) |
+| `tool_call_end` | `{ call_id, tool_name, output, success, duration_ms, metadata? }` | Tool execution completed |
+| `approval_request` | `{ call_id, command, cwd }` | Awaiting user approval |
+
+#### Task Lifecycle
+
+| `type` | Fields | Description |
+|--------|--------|-------------|
+| `task_started` | `{}` | Agent task began |
+| `task_complete` | `{ message? }` | Agent task finished |
+| `cancelled` | `{}` | Operation was cancelled |
+
+#### Session Management
+
+| `type` | Fields | Description |
+|--------|--------|-------------|
+| `joined_session` | `{ session_id }` | Joined a session |
+| `session_configured` | `{ session_id, model, cwd }` | Session configured by CLI |
+| `model_updated` | `{ model }` | Model changed |
+| `session_closed` | `{}` | Session ended |
+
+#### Metadata
+
+| `type` | Fields | Description |
+|--------|--------|-------------|
+| `token_usage` | `{ input_tokens, output_tokens, total_tokens }` | Token count update |
+| `message_received` | `{ id, role, content }` | Message echo |
+| `status` | `{ connected, authenticated, session_id?, uptime_seconds }` | Connection status |
+
+#### Errors
+
+| `type` | Fields | Description |
+|--------|--------|-------------|
+| `error` | `{ code, message }` | Error message |
+| `warning` | `{ message }` | Warning message |
+
+#### Terminal
+
+| `type` | Fields | Description |
+|--------|--------|-------------|
+| `terminal_created` | `{ terminal_id, name, cwd }` | Terminal created |
+| `terminal_output` | `{ terminal_id, timestamp, content, stream }` | Terminal output |
+| `terminal_status` | `{ terminal_id, status, exit_code? }` | Terminal status change |
+| `terminal_list` | `{ terminals }` | Terminal list |
+
+#### Design System
+
+| `type` | Fields | Description |
+|--------|--------|-------------|
+| `design_system_pending` | `{ call_id, project_type, fonts, palettes }` | Awaiting design system selection |
+| `design_system_received` | `{ call_id }` | Design system selection received |
+
+---
+
+## Pipeline 2: Legacy AI Module (`"ai:*"` events)
+
+### Events
+
+#### `"ai:stream_chunk"`
+
+- **Emitter:** `src-tauri/src/ai/mod.rs` → `ai_stream` command
+- **Payload:** `{ threadId: string, content: string, done: boolean }`
+- **Listeners:**
+  - `src/context/AIContext.tsx` → `setupEventListeners()`
+  - `src/context/ai/AIStreamContext.tsx` → `setupEventListeners()`
+  - `src/components/ai/InlineAssistant.tsx` → `listen("ai:stream_chunk", ...)`
+
+#### `"ai:tool_call"`
+
+- **Emitter:** `src-tauri/src/ai/mod.rs` → `ai_stream` command (when `StreamChunk.tool_calls` is present)
+- **Payload:** `{ threadId: string, callId: string, name: string, arguments: string }`
+- **Listeners:**
+  - `src/context/AIContext.tsx` → `setupEventListeners()`
+  - `src/context/ai/AIStreamContext.tsx` → `setupEventListeners()`
+
+#### `"ai:tool_result"`
+
+- **Emitter:** Not currently emitted by backend (tool results flow through `"cortex-event"` pipeline)
+- **Payload:** `{ threadId: string, callId: string, output: string, success: boolean, durationMs?: number }`
+- **Listeners:**
+  - `src/context/AIContext.tsx` → `setupEventListeners()`
+  - `src/context/ai/AIStreamContext.tsx` → `setupEventListeners()`
+  - `src/components/cortex/CortexAIModificationsPanel.tsx` → `listen("ai:tool_result", ...)`
+
+#### `"ai:error"`
+
+- **Emitter:** Not currently emitted by backend (errors flow through `"cortex-event"` pipeline)
+- **Payload:** `{ code: string, message: string }`
+- **Listeners:**
+  - `src/context/AIContext.tsx` → `setupEventListeners()`
+  - `src/context/ai/AIStreamContext.tsx` → `setupEventListeners()`
+
+#### `"ai:completion_stream"`
+
+- **Emitter:** `src-tauri/src/ai/completions.rs` → `ai_inline_completion` command
+- **Payload:** `{ requestId: string, delta: string, done: boolean }`
+- **Listeners:**
+  - `src/providers/InlineCompletionsProvider.ts` → `listen("ai:completion_stream", ...)`
+
+#### `"ai:index_progress"`
+
+- **Emitter:** `src-tauri/src/ai/indexer.rs`
+- **Payload:** `{ totalFiles, indexedFiles, totalChunks, done, currentFile }`
+- **Listeners:**
+  - `src/context/ai/AIAgentContext.tsx` → `listen("ai:index_progress", ...)`
+
+#### `"ai:agent_status"`
+
+- **Emitter:** `src-tauri/src/ai/agents/commands.rs` (via agent lifecycle events)
+- **Payload:** `{ agentId: string, status: string }`
+- **Listeners:**
+  - `src/context/ai/AIAgentContext.tsx` → `listen("ai:agent_status", ...)`
+
+---
+
+## Other AI-Related Events
+
+#### `"agent-action"`
+
+- **Emitter:** `src-tauri/src/ai/session.rs` → `log_action()`
+- **Payload:** `{ action: { type, ... }, description, category }`
+- **Listeners:**
+  - `src/context/AgentFollowContext.tsx` → `listen("agent-action", ...)`
+
+#### `"openrouter:stream"`
+
+- **Emitter:** `src-tauri/src/ai/openrouter_commands.rs` → `openrouter_stream_chat`
+- **Payload:** `{ threadId: string, chunk: StreamChunk }`
+- **Listeners:**
+  - `src/utils/llm/OpenRouterProvider.ts` → `listen("openrouter:stream", ...)`
+
+#### Agent Lifecycle Events
+
+| Event | Emitter | Payload |
+|-------|---------|---------|
+| `"agent:spawned"` | `agents/commands.rs` | `{ agent: Agent }` |
+| `"agent:task_started"` | `agents/commands.rs` | `{ agentId, prompt }` |
+| `"agent:task_progress"` | `agents/commands.rs` | Progress chunk |
+| `"agent:task_completed"` | `agents/commands.rs` | `{ task: Task }` |
+| `"agent:task_failed"` | `agents/commands.rs` | `{ agentId, error }` |
+| `"agent:task_cancelled"` | `agents/commands.rs` | `{ taskId }` |
+| `"agent:removed"` | `agents/commands.rs` | `{ agentId }` |

src-tauri/src/ai/mod.rs

@@ -167,10 +167,15 @@ pub async fn ai_complete(
         .map_err(|e| e.to_string())
 }
 
-/// Stream a conversation response
+/// Stream a conversation response.
 ///
-/// Emits "ai:stream_chunk" events with StreamChunk payloads.
-/// Event payload includes thread_id for routing to correct UI component.
+/// **Tauri Event:** `"ai:stream_chunk"`
+/// **Payload:** `{ threadId: string, content: string, done: bool }`
+/// **Direction:** Backend → Frontend
+/// **Listeners:** `AIContext.tsx`, `AIStreamContext.tsx`, `InlineAssistant.tsx`
+///
+/// When `chunk.tool_calls` is present, also emits `"ai:tool_call"` events
+/// with payload `{ threadId, callId, name, arguments }`.
 #[tauri::command]
 pub async fn ai_stream(
     app: AppHandle,
@@ -189,9 +194,27 @@ pub async fn ai_stream(
     let app_clone = app.clone();
     tauri::async_runtime::spawn(async move {
         while let Some(chunk) = rx.recv().await {
+            // Emit tool_call events if tool calls are present in this chunk
+            if let Some(ref tool_calls) = chunk.tool_calls {
+                for tc in tool_calls {
+                    if let Some(ref id) = tc.id {
+                        let tool_payload = ToolCallPayload {
+                            thread_id: thread_id_clone.clone(),
+                            call_id: id.clone(),
+                            name: tc.function.name.clone(),
+                            arguments: tc.function.arguments.clone(),
+                        };
+                        if let Err(e) = app_clone.emit("ai:tool_call", &tool_payload) {
+                            error!("Failed to emit tool_call event: {}", e);
+                        }
+                    }
+                }
+            }
+
             let event_payload = StreamEventPayload {
                 thread_id: thread_id_clone.clone(),
-                chunk,
+                content: chunk.content,
+                done: chunk.done,
             };
             if let Err(e) = app_clone.emit("ai:stream_chunk", &event_payload) {
                 error!("Failed to emit stream event: {}", e);
@@ -208,12 +231,25 @@ pub async fn ai_stream(
     Ok(())
 }
 
-/// Payload for stream events
+/// Flattened payload for `"ai:stream_chunk"` events.
+/// Matches the frontend `StreamChunkEvent` interface: `{ threadId, content, done }`.
 #[derive(Debug, Clone, serde::Serialize)]
 #[serde(rename_all = "camelCase")]
 struct StreamEventPayload {
     thread_id: String,
-    chunk: StreamChunk,
+    content: String,
+    done: bool,
+}
+
+/// Payload for `"ai:tool_call"` events.
+/// Matches the frontend `ToolCallEvent` interface.
+#[derive(Debug, Clone, serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+struct ToolCallPayload {
+    thread_id: String,
+    call_id: String,
+    name: String,
+    arguments: String,
 }
 
 // =============================================================================

src-tauri/src/ai/protocol.rs

@@ -8,8 +8,17 @@ pub struct TokenUsageInfo {
     pub total_tokens: u32,
 }
 
-/// Server-to-client WebSocket messages.
-/// Adapted for Tauri event emitting.
+/// Server-to-client messages emitted via the `"cortex-event"` Tauri event channel.
+///
+/// This is the **primary AI pipeline** used by `SDKContext.tsx` and `AgentPanel.tsx`.
+/// Events are serialized with `#[serde(tag = "type", rename_all = "snake_case")]`,
+/// so each variant becomes a `{ type: "variant_name", ...fields }` JSON object.
+///
+/// **Tauri Event:** `"cortex-event"`
+/// **Direction:** Backend (`session.rs`) → Frontend (`SDKContext.tsx`)
+/// **Emitter:** `convert_event_to_ws()` in `session.rs`
+///
+/// See also: `docs/AI_EVENT_CONTRACTS.md` for the full event contract reference.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(tag = "type", rename_all = "snake_case")]
 pub enum WsMessage {

src/context/SDKContext.tsx

@@ -800,7 +800,11 @@ export function SDKProvider(props: ParentProps) {
     }
   });
 
-  // Listen for Tauri cortex events
+  // Listen for Tauri cortex events (Primary AI Pipeline)
+  // Event: "cortex-event" — emitted by session.rs via convert_event_to_ws()
+  // Payload: WsMessage (see src-tauri/src/ai/protocol.rs) with { type: "...", ...fields }
+  // Handles: stream_chunk, agent_message, tool_call_begin/end, task_started/complete,
+  //          approval_request, token_usage, error, reasoning_delta, terminal events, etc.
   useTauriListen<CortexEvent>("cortex-event", (payload) => {
     processMessage(payload);
   });

src/context/__tests__/AIContext.test.tsx

@@ -357,36 +357,36 @@ describe("AIContext", () => {
   });
 
   describe("Streaming Events", () => {
-    it("should listen for stream start event", async () => {
+    it("should listen for stream chunk event", async () => {
       vi.mocked(listen).mockResolvedValueOnce(() => {});
 
-      await listen("ai:stream-start", () => {});
+      await listen("ai:stream_chunk", () => {});
 
-      expect(listen).toHaveBeenCalledWith("ai:stream-start", expect.any(Function));
+      expect(listen).toHaveBeenCalledWith("ai:stream_chunk", expect.any(Function));
     });
 
-    it("should listen for stream chunk event", async () => {
+    it("should listen for tool call event", async () => {
       vi.mocked(listen).mockResolvedValueOnce(() => {});
 
-      await listen("ai:stream-chunk", () => {});
+      await listen("ai:tool_call", () => {});
 
-      expect(listen).toHaveBeenCalledWith("ai:stream-chunk", expect.any(Function));
+      expect(listen).toHaveBeenCalledWith("ai:tool_call", expect.any(Function));
     });
 
-    it("should listen for stream end event", async () => {
+    it("should listen for tool result event", async () => {
       vi.mocked(listen).mockResolvedValueOnce(() => {});
 
-      await listen("ai:stream-end", () => {});
+      await listen("ai:tool_result", () => {});
 
-      expect(listen).toHaveBeenCalledWith("ai:stream-end", expect.any(Function));
+      expect(listen).toHaveBeenCalledWith("ai:tool_result", expect.any(Function));
     });
 
     it("should listen for stream error event", async () => {
       vi.mocked(listen).mockResolvedValueOnce(() => {});
 
-      await listen("ai:stream-error", () => {});
+      await listen("ai:error", () => {});
 
-      expect(listen).toHaveBeenCalledWith("ai:stream-error", expect.any(Function));
+      expect(listen).toHaveBeenCalledWith("ai:error", expect.any(Function));
     });
   });
 

src/context/ai/AIStreamContext.tsx

@@ -1,6 +1,18 @@
 /**
- * AIStreamContext - Manages AI streaming state
- * 
+ * AIStreamContext - Manages AI streaming state (Legacy Pipeline)
+ *
+ * This context listens to the **legacy AI event pipeline** (`"ai:*"` events)
+ * emitted by the `ai_stream` Tauri command in `src-tauri/src/ai/mod.rs`.
+ *
+ * **Events consumed:**
+ * - `"ai:stream_chunk"` → `{ threadId, content, done }` — streaming content deltas
+ * - `"ai:tool_call"` → `{ threadId, callId, name, arguments }` — tool call notifications
+ * - `"ai:tool_result"` → `{ threadId, callId, output, success, durationMs? }` — tool results
+ * - `"ai:error"` → `{ code, message }` — error notifications
+ *
+ * **Note:** The primary AI pipeline uses `"cortex-event"` via `SDKContext.tsx` instead.
+ * This context is used by `InlineAssistant.tsx` and direct model streaming features.
+ *
  * Handles:
  * - Streaming content accumulation
  * - Stream cancellation