feat(console): add initial console for Cursor BYOK with provider management and LLM call tracking

cursor-server/src/cursor/actor.rs

@@ -0,0 +1,246 @@
+use std::sync::Arc;
+
+use tokio::sync::mpsc;
+
+use crate::{
+    cursor::prompting::PromptCompiler,
+    cursor::{
+        blob_sync::BlobSynchronizer,
+        checkpoint::CheckpointBuilder,
+        proto::agent::v1 as pb,
+        request,
+        session::CursorSession,
+        tools::{
+            codec, result::tool_result_channel, runtime::CursorToolRuntime, ClientToolEvent,
+            ToolDispatcher,
+        },
+    },
+    provider::Provider,
+    run::{RunActor, RunRegistry},
+    store::Store,
+};
+
+use super::{inbox::OrderedInbox, CursorCommand, CursorSessionHandle};
+
+pub struct CursorActor;
+
+#[derive(Clone)]
+pub(crate) struct RunDependencies {
+    pub store: Store,
+    pub provider: Arc<dyn Provider>,
+    pub compiler: PromptCompiler,
+    pub run_registry: RunRegistry,
+}
+
+impl CursorActor {
+    pub(crate) fn spawn(
+        handle: CursorSessionHandle,
+        mut receiver: mpsc::Receiver<CursorCommand>,
+        dependencies: RunDependencies,
+        blob_sync: BlobSynchronizer,
+        next_append_seqno: i64,
+    ) {
+        tokio::spawn(async move {
+            let mut inbox = OrderedInbox::starting_at(next_append_seqno);
+            let (results_tx, results_rx) = tool_result_channel();
+            let tool_runtime = CursorToolRuntime::default();
+            let tools = ToolDispatcher::with_results(tool_runtime.clone(), results_tx.clone());
+            let mut run_resources = Some((results_rx, dependencies));
+            loop {
+                let command = match receiver.recv().await {
+                    Some(command) => command,
+                    None => {
+                        handle.cancel();
+                        break;
+                    }
+                };
+                match command {
+                    CursorCommand::Abort => {
+                        handle.cancel();
+                    }
+                    CursorCommand::Finished => {
+                        break;
+                    }
+                    CursorCommand::Append { seqno, message } => {
+                        for (_seqno, message) in inbox.push(seqno, *message) {
+                            {
+                                match message.message {
+                                    Some(pb::agent_client_message::Message::RunRequest(
+                                        request,
+                                    )) => {
+                                        if let Some((results, dependencies)) = run_resources.take()
+                                        {
+                                            let handle = handle.clone();
+                                            let blob_sync = blob_sync.clone();
+                                            let tools = tools.clone();
+                                            let tool_runtime = tool_runtime.clone();
+                                            tokio::spawn(async move {
+                                                let mut checkpoint = CheckpointBuilder::new(
+                                                    dependencies.store.clone(),
+                                                    blob_sync.clone(),
+                                                    handle
+                                                        .parent()
+                                                        .map(|parent| parent.tool_call_id.clone()),
+                                                    request.conversation_state.clone(),
+                                                );
+                                                let parent = handle.parent().map(|parent| {
+                                                    (
+                                                        crate::model::RunId::new(&parent.run_id),
+                                                        parent.tool_call_id.clone(),
+                                                    )
+                                                });
+                                                let prepared = request::prepare(
+                                                    handle.request_id(),
+                                                    &request,
+                                                    parent,
+                                                    request::PrepareDependencies {
+                                                        compiler: &dependencies.compiler,
+                                                        store: &dependencies.store,
+                                                        checkpoint: &checkpoint,
+                                                        blob_sync: &blob_sync,
+                                                    },
+                                                )
+                                                .await;
+                                                let (prepared, context) = match prepared {
+                                                    Ok(prepared) => prepared,
+                                                    Err(error) => {
+                                                        tracing::error!(
+                                                            request_id = handle.request_id(),
+                                                            %error,
+                                                            "failed to prepare Cursor Run"
+                                                        );
+                                                        let _ = crate::cursor::lifecycle::fail(
+                                                            &handle, &error,
+                                                        );
+                                                        let _ = handle
+                                                            .command(CursorCommand::Finished)
+                                                            .await;
+                                                        return;
+                                                    }
+                                                };
+                                                checkpoint.configure(
+                                                    prepared.model.model_id.clone(),
+                                                    prepared.model.context_window_tokens,
+                                                    prepared.prompt.instructions.clone(),
+                                                    prepared.prompt.tools.clone(),
+                                                    context.dynamic_tools.keys().cloned().collect(),
+                                                    context.turn_user.clone(),
+                                                );
+                                                let cancellation = handle.cancellation();
+                                                let (port, core) = crate::client::session(256);
+                                                let actor = RunActor::new(
+                                                    dependencies.store.clone(),
+                                                    dependencies.provider,
+                                                    dependencies.run_registry,
+                                                );
+                                                let core_run =
+                                                    actor.spawn(prepared, port, cancellation).await;
+                                                let session = CursorSession::new(
+                                                    handle.clone(),
+                                                    dependencies.store,
+                                                    context,
+                                                    core,
+                                                    super::session::CursorSessionRuntime {
+                                                        tools,
+                                                        results,
+                                                        checkpoint,
+                                                        tool_runtime,
+                                                    },
+                                                );
+                                                if let Err(error) = session.run().await {
+                                                    tracing::error!(
+                                                        request_id = handle.request_id(),
+                                                        %error,
+                                                        "Cursor session failed"
+                                                    );
+                                                    handle.cancel();
+                                                    let _ = crate::cursor::lifecycle::fail(
+                                                        &handle, &error,
+                                                    );
+                                                }
+                                                let _ = core_run.await;
+                                                let _ =
+                                                    handle.command(CursorCommand::Finished).await;
+                                            });
+                                        }
+                                    }
+                                    Some(pb::agent_client_message::Message::ExecClientMessage(
+                                        message,
+                                    )) => {
+                                        match codec::client_event(&message, &tool_runtime).await {
+                                            Ok(codec::ClientExecEvent::Delta(message)) => {
+                                                let _ = handle.emit(&message);
+                                            }
+                                            Ok(codec::ClientExecEvent::Message(message)) => {
+                                                let _ = handle.emit(&message);
+                                            }
+                                            Ok(codec::ClientExecEvent::Completed(result)) => {
+                                                results_tx.send(*result)
+                                            }
+                                            Ok(codec::ClientExecEvent::Pending) => {}
+                                            Err(error) => results_tx.send_error(error),
+                                        }
+                                    }
+                                    Some(
+                                        pb::agent_client_message::Message::ExecClientControlMessage(
+                                            message,
+                                        ),
+                                    ) => {
+                                        use pb::exec_client_control_message::Message;
+                                        match message.message {
+                                            Some(Message::StreamClose(close)) => {
+                                                if tool_runtime.take_exec(close.id).await.is_some()
+                                                {
+                                                    results_tx.send_error(crate::Error::Protocol(format!(
+                                                        "Exec stream closed before result for id: {}",
+                                                        close.id
+                                                    )));
+                                                }
+                                            }
+                                            Some(Message::Throw(throw)) => {
+                                                match tool_runtime.take_exec(throw.id).await {
+                                                    Some(pending) => results_tx.send_error(
+                                                        crate::Error::Protocol(format!(
+                                                            "Exec {} failed: {}",
+                                                            pending.call.call_id, throw.error
+                                                        )),
+                                                    ),
+                                                    None => results_tx.send_error(
+                                                        crate::Error::Protocol(format!(
+                                                            "unknown ExecClientThrow id: {}",
+                                                            throw.id
+                                                        )),
+                                                    ),
+                                                }
+                                            }
+                                            Some(Message::Heartbeat(_)) | None => {}
+                                        }
+                                    }
+                                    Some(
+                                        pb::agent_client_message::Message::InteractionResponse(
+                                            message,
+                                        ),
+                                    ) => match tools.interaction_response(&message).await {
+                                        Ok(ClientToolEvent::Message(message)) => {
+                                            let _ = handle.emit(&message);
+                                        }
+                                        Ok(ClientToolEvent::Completed(completion)) => {
+                                            results_tx.send(*completion)
+                                        }
+                                        Err(error) => results_tx.send_error(error),
+                                    },
+                                    Some(pb::agent_client_message::Message::KvClientMessage(
+                                        message,
+                                    )) => {
+                                        let _ = blob_sync.handle_client(message).await;
+                                    }
+                                    _ => {}
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        });
+    }
+}

cursor-server/src/cursor/bidi_append.rs

@@ -2,13 +2,14 @@ use prost::Message;
 
 use crate::{
     cursor::proto::{agent::v1 as agent, aiserver::v1 as ai},
-    run::{RunCommand, RunRegistry},
+    cursor::{CursorCommand, CursorParent, CursorSessionRegistry},
     Error, Result,
 };
 
 pub async fn append(
-    registry: &RunRegistry,
+    registry: &CursorSessionRegistry,
     request: ai::BidiAppendRequest,
+    parent: Option<CursorParent>,
 ) -> Result<ai::BidiAppendResponse> {
     let request_id = request
         .request_id
@@ -29,17 +30,12 @@ pub async fn append(
     let payload = hex::decode(&request.data)
         .map_err(|error| Error::Protocol(format!("invalid BidiAppend hex: {error}")))?;
     let message = agent::AgentClientMessage::decode(payload.as_slice())?;
-    if let Some(agent::agent_client_message::Message::RunRequest(run)) = &message.message {
-        if let Some(conversation_id) = run.conversation_id.as_deref() {
-            registry
-                .bind_conversation(conversation_id, request_id)
-                .await;
-        }
+    let handle = registry.get_or_create(request_id).await?;
+    if let Some(parent) = parent {
+        handle.set_parent(parent)?;
     }
-    registry
-        .get_or_create(request_id)
-        .await?
-        .command(RunCommand::Append {
+    handle
+        .command(CursorCommand::Append {
             seqno: request.append_seqno,
             message: Box::new(message),
         })

cursor-server/src/cursor/blob_sync.rs

@@ -1,5 +1,5 @@
 use std::{
-    collections::HashMap,
+    collections::{HashMap, HashSet},
     sync::{
         atomic::{AtomicU32, Ordering},
         Arc,
@@ -7,17 +7,16 @@ use std::{
     time::Duration,
 };
 
-use prost::Message;
-use tokio::sync::{oneshot, Mutex, Notify};
+use tokio::sync::{oneshot, Mutex};
 
 use crate::{
     cursor::proto::agent::v1 as pb,
-    run::RunHandle,
+    cursor::CursorSessionHandle,
     store::{BlobEdge, BlobId, Store},
     Error, Result,
 };
 
-type BlobGetSender = oneshot::Sender<Result<Option<Vec<u8>>>>;
+type BlobSetSender = oneshot::Sender<Result<()>>;
 
 #[derive(Clone)]
 pub struct BlobSynchronizer {
@@ -27,15 +26,26 @@ pub struct BlobSynchronizer {
 struct Inner {
     request_id: String,
     store: Store,
-    handle: RunHandle,
+    handle: CursorSessionHandle,
     next_id: AtomicU32,
-    set_requests: Mutex<HashMap<u32, BlobId>>,
-    get_requests: Mutex<HashMap<u32, BlobGetSender>>,
-    ack: Notify,
+    set_requests: Mutex<HashMap<u32, PendingSet>>,
+    acked_blobs: Mutex<HashSet<BlobId>>,
+    get_requests: Mutex<HashMap<u32, PendingGet>>,
+}
+
+struct PendingSet {
+    blob_id: BlobId,
+    sent_at: std::time::Instant,
+    result: BlobSetSender,
+}
+
+struct PendingGet {
+    blob_id: BlobId,
+    result: oneshot::Sender<Result<Option<Vec<u8>>>>,
 }
 
 impl BlobSynchronizer {
-    pub fn new(request_id: String, store: Store, handle: RunHandle) -> Self {
+    pub fn new(request_id: String, store: Store, handle: CursorSessionHandle) -> Self {
         Self {
             inner: Arc::new(Inner {
                 request_id,
@@ -43,8 +53,8 @@ impl BlobSynchronizer {
                 handle,
                 next_id: AtomicU32::new(1),
                 set_requests: Mutex::new(HashMap::new()),
+                acked_blobs: Mutex::new(HashSet::new()),
                 get_requests: Mutex::new(HashMap::new()),
-                ack: Notify::new(),
             }),
         }
     }
@@ -53,97 +63,54 @@ impl BlobSynchronizer {
         &self.inner.request_id
     }
 
-    pub async fn recover(&self) -> Result<()> {
-        for item in self
-            .inner
-            .store
-            .pending_outbox(&self.inner.request_id)
-            .await?
-        {
-            if item.kind != "kv_set" {
-                continue;
-            }
-            let encoded = item
-                .key
-                .strip_prefix("blob:")
-                .ok_or_else(|| Error::Protocol(format!("invalid Blob outbox key: {}", item.key)))?;
-            let blob_id = BlobId::from_base64(encoded)?;
-            let id = self.inner.next_id.fetch_add(1, Ordering::Relaxed);
-            self.inner
-                .set_requests
-                .lock()
-                .await
-                .insert(id, blob_id.clone());
-            self.inner.handle.emit(&pb::AgentServerMessage {
-                ttft_breakdown: None,
-                message: Some(pb::agent_server_message::Message::KvServerMessage(
-                    pb::KvServerMessage {
-                        id,
-                        span_context: None,
-                        message: Some(pb::kv_server_message::Message::SetBlobArgs(
-                            pb::SetBlobArgs {
-                                blob_id: blob_id.as_bytes().to_vec(),
-                                blob_data: item.payload,
-                            },
-                        )),
-                    },
-                )),
-            })?;
-            self.inner.store.mark_outbox_sent(item.id).await?;
-        }
-        self.publish_ready_checkpoints().await
-    }
-
     pub async fn persist(&self, data: &[u8], edges: &[BlobEdge]) -> Result<BlobId> {
         let id = self.inner.store.put_blob(data, edges).await?;
-        let key = format!("blob:{}", id.to_base64());
-        self.inner
-            .store
-            .enqueue_outbox(&self.inner.request_id, &key, "kv_set", data, &[])
-            .await?;
         self.ensure_set(&id, data).await?;
         Ok(id)
     }
 
     async fn ensure_set(&self, blob_id: &BlobId, data: &[u8]) -> Result<()> {
-        let dependency = [blob_id.clone()];
-        loop {
-            if self
-                .inner
-                .store
-                .dependencies_acked(&self.inner.request_id, &dependency)
-                .await?
-            {
-                return Ok(());
-            }
-            let id = self.inner.next_id.fetch_add(1, Ordering::Relaxed);
-            self.inner
-                .set_requests
-                .lock()
-                .await
-                .insert(id, blob_id.clone());
-            self.inner.handle.emit(&pb::AgentServerMessage {
-                ttft_breakdown: None,
-                message: Some(pb::agent_server_message::Message::KvServerMessage(
-                    pb::KvServerMessage {
-                        id,
-                        span_context: None,
-                        message: Some(pb::kv_server_message::Message::SetBlobArgs(
-                            pb::SetBlobArgs {
-                                blob_id: blob_id.as_bytes().to_vec(),
-                                blob_data: data.to_vec(),
-                            },
-                        )),
-                    },
-                )),
-            })?;
-            let cancellation = self.inner.handle.cancellation();
-            tokio::select! {
-                _ = self.inner.ack.notified() => {}
-                _ = tokio::time::sleep(Duration::from_secs(2)) => {}
-                _ = cancellation.cancelled() => return Err(Error::Cancelled),
-            }
+        if self.inner.acked_blobs.lock().await.contains(blob_id) {
+            return Ok(());
         }
+        let id = self.inner.next_id.fetch_add(1, Ordering::Relaxed);
+        let (sender, receiver) = oneshot::channel();
+        self.inner.set_requests.lock().await.insert(
+            id,
+            PendingSet {
+                blob_id: blob_id.clone(),
+                sent_at: std::time::Instant::now(),
+                result: sender,
+            },
+        );
+        if let Err(error) = self.inner.handle.emit(&pb::AgentServerMessage {
+            ttft_breakdown: None,
+            message: Some(pb::agent_server_message::Message::KvServerMessage(
+                pb::KvServerMessage {
+                    id,
+                    span_context: None,
+                    message: Some(pb::kv_server_message::Message::SetBlobArgs(
+                        pb::SetBlobArgs {
+                            blob_id: blob_id.as_bytes().to_vec(),
+                            blob_data: data.to_vec(),
+                        },
+                    )),
+                },
+            )),
+        }) {
+            self.inner.set_requests.lock().await.remove(&id);
+            return Err(error);
+        }
+        let cancellation = self.inner.handle.cancellation();
+        let result = tokio::select! {
+            result = receiver => result.map_err(|_| Error::Protocol("KV SET response channel closed".into()))?,
+            _ = cancellation.cancelled() => Err(Error::Cancelled),
+            _ = tokio::time::sleep(Duration::from_secs(15)) => Err(Error::Protocol(format!("KV SET timed out: {}", blob_id.to_base64()))),
+        };
+        if result.is_err() {
+            self.inner.set_requests.lock().await.remove(&id);
+        }
+        result
     }
 
     pub async fn get(&self, blob_id: &BlobId) -> Result<Option<Vec<u8>>> {
@@ -152,7 +119,13 @@ impl BlobSynchronizer {
         }
         let id = self.inner.next_id.fetch_add(1, Ordering::Relaxed);
         let (sender, receiver) = oneshot::channel();
-        self.inner.get_requests.lock().await.insert(id, sender);
+        self.inner.get_requests.lock().await.insert(
+            id,
+            PendingGet {
+                blob_id: blob_id.clone(),
+                result: sender,
+            },
+        );
         self.inner.handle.emit(&pb::AgentServerMessage {
             ttft_breakdown: None,
             message: Some(pb::agent_server_message::Message::KvServerMessage(
@@ -168,81 +141,96 @@ impl BlobSynchronizer {
             )),
         })?;
         let cancellation = self.inner.handle.cancellation();
-        tokio::select! {
+        let result = tokio::select! {
             result = receiver => result.map_err(|_| Error::Protocol("KV GET response channel closed".into()))?,
             _ = cancellation.cancelled() => Err(Error::Cancelled),
             _ = tokio::time::sleep(Duration::from_secs(15)) => Err(Error::Protocol(format!("KV GET timed out: {}", blob_id.to_base64()))),
+        };
+        if result.is_err() {
+            self.inner.get_requests.lock().await.remove(&id);
         }
+        result
+    }
+
+    pub async fn cache_received(&self, blob_id: &BlobId, data: &[u8]) -> Result<()> {
+        let actual = BlobId::digest(data);
+        if actual != *blob_id {
+            return Err(Error::Protocol(format!(
+                "received Blob hash mismatch: expected {}, got {}",
+                blob_id.to_base64(),
+                actual.to_base64()
+            )));
+        }
+        self.inner.store.put_blob(data, &[]).await?;
+        Ok(())
     }
 
     pub async fn handle_client(&self, message: pb::KvClientMessage) -> Result<()> {
         match message.message {
             Some(pb::kv_client_message::Message::SetBlobResult(result)) => {
-                if result.error.is_none() {
-                    if let Some(blob_id) = self.inner.set_requests.lock().await.remove(&message.id)
-                    {
-                        self.inner
-                            .store
-                            .ack_outbox(
-                                &self.inner.request_id,
-                                &format!("blob:{}", blob_id.to_base64()),
-                            )
-                            .await?;
-                        self.inner.ack.notify_waiters();
+                if let Some(pending) = self.inner.set_requests.lock().await.remove(&message.id) {
+                    if let Some(error) = result.error {
+                        tracing::error!(
+                            request_id = self.request_id(),
+                            kv_id = message.id,
+                            blob_id = pending.blob_id.to_base64(),
+                            error = error.message,
+                            "Cursor rejected Blob SET"
+                        );
+                        let _ = pending.result.send(Err(Error::Protocol(format!(
+                            "KV SET {}: {}",
+                            pending.blob_id.to_base64(),
+                            error.message
+                        ))));
+                    } else {
+                        tracing::debug!(
+                            request_id = self.request_id(),
+                            kv_id = message.id,
+                            blob_id = pending.blob_id.to_base64(),
+                            elapsed_ms = pending.sent_at.elapsed().as_millis(),
+                            "Cursor acknowledged Blob SET"
+                        );
+                        self.inner.acked_blobs.lock().await.insert(pending.blob_id);
+                        let _ = pending.result.send(Ok(()));
                     }
+                } else {
+                    tracing::warn!(
+                        request_id = self.request_id(),
+                        kv_id = message.id,
+                        "unknown Cursor Blob SET acknowledgement"
+                    );
                 }
             }
             Some(pb::kv_client_message::Message::GetBlobResult(result)) => {
-                if let Some(sender) = self.inner.get_requests.lock().await.remove(&message.id) {
+                if let Some(pending) = self.inner.get_requests.lock().await.remove(&message.id) {
                     let value = if let Some(error) = result.error {
                         Err(Error::Protocol(format!("KV GET: {}", error.message)))
+                    } else if let Some(data) = result.blob_data {
+                        let actual = BlobId::digest(&data);
+                        if actual != pending.blob_id {
+                            Err(Error::Protocol(format!(
+                                "KV GET Blob hash mismatch: expected {}, got {}",
+                                pending.blob_id.to_base64(),
+                                actual.to_base64()
+                            )))
+                        } else {
+                            self.inner.store.put_blob(&data, &[]).await?;
+                            Ok(Some(data))
+                        }
                     } else {
-                        Ok(result.blob_data)
+                        Ok(None)
                     };
-                    let _ = sender.send(value);
+                    let _ = pending.result.send(value);
+                } else {
+                    tracing::warn!(
+                        request_id = self.request_id(),
+                        kv_id = message.id,
+                        "unknown Cursor Blob GET response"
+                    );
                 }
             }
             None => {}
         }
-        self.publish_ready_checkpoints().await?;
-        Ok(())
-    }
-
-    async fn publish_ready_checkpoints(&self) -> Result<()> {
-        for item in self
-            .inner
-            .store
-            .pending_outbox(&self.inner.request_id)
-            .await?
-        {
-            if item.kind != "checkpoint" {
-                continue;
-            }
-            let dependencies = item
-                .dependencies
-                .iter()
-                .map(|id| BlobId::from_base64(id))
-                .collect::<Result<Vec<_>>>()?;
-            if !self
-                .inner
-                .store
-                .dependencies_acked(&self.inner.request_id, &dependencies)
-                .await?
-            {
-                continue;
-            }
-            let checkpoint = pb::ConversationStateStructure::decode(item.payload.as_slice())?;
-            self.inner.handle.emit(&pb::AgentServerMessage {
-                ttft_breakdown: None,
-                message: Some(
-                    pb::agent_server_message::Message::ConversationCheckpointUpdate(checkpoint),
-                ),
-            })?;
-            self.inner
-                .store
-                .ack_outbox(&self.inner.request_id, &item.key)
-                .await?;
-        }
         Ok(())
     }
 }

cursor-server/src/cursor/checkpoint.rs

@@ -1,384 +0,0 @@
-use prost::Message;
-
-use std::collections::HashSet;
-
-use crate::{
-    cursor::{blob_sync::BlobSynchronizer, interaction::render_tool_call, proto::agent::v1 as pb},
-    model::{CanonicalMessage, MessageContent, Origin, Role, ToolCall},
-    prompting::fold_derived_state,
-    run::RunHandle,
-    store::{BlobEdge, BlobId, Store},
-    Error, Result,
-};
-
-pub struct CheckpointBuilder {
-    store: Store,
-    sync: BlobSynchronizer,
-}
-
-impl CheckpointBuilder {
-    pub fn new(store: Store, sync: BlobSynchronizer) -> Self {
-        Self { store, sync }
-    }
-
-    pub async fn build(
-        &self,
-        conversation_id: &str,
-        revision: i64,
-        messages: &[CanonicalMessage],
-        mode: i32,
-    ) -> Result<pb::ConversationStateStructure> {
-        self.build_with_tool_progress(
-            conversation_id,
-            revision,
-            messages,
-            mode,
-            &[],
-            &HashSet::new(),
-        )
-        .await
-    }
-
-    pub async fn build_with_tool_progress(
-        &self,
-        conversation_id: &str,
-        revision: i64,
-        messages: &[CanonicalMessage],
-        mode: i32,
-        active_calls: &[ToolCall],
-        completed: &HashSet<String>,
-    ) -> Result<pb::ConversationStateStructure> {
-        let mut root_ids = Vec::with_capacity(messages.len());
-        for message in messages {
-            root_ids.push(
-                self.sync
-                    .persist(&serde_json::to_vec(message)?, &[])
-                    .await?,
-            );
-        }
-        let turn_ids = self.build_turns(messages, mode, completed).await?;
-        let (todo_ids, plan_id) = self.build_derived_state(messages).await?;
-        let checkpoint = pb::ConversationStateStructure {
-            root_prompt_messages_json: root_ids.iter().map(|id| id.as_bytes().to_vec()).collect(),
-            turns: turn_ids.iter().map(|id| id.as_bytes().to_vec()).collect(),
-            todos: todo_ids.iter().map(|id| id.as_bytes().to_vec()).collect(),
-            plan: plan_id.as_ref().map(|id| id.as_bytes().to_vec()),
-            pending_tool_calls: active_calls
-                .iter()
-                .filter(|call| !completed.contains(&call.call_id))
-                .map(|call| call.call_id.clone())
-                .collect(),
-            mode: Some(mode),
-            ..Default::default()
-        };
-        let mut encoded = Vec::new();
-        checkpoint.encode(&mut encoded)?;
-        let mut edges = root_ids
-            .iter()
-            .enumerate()
-            .map(|(index, child)| BlobEdge {
-                child: child.clone(),
-                field_name: format!("root_prompt_messages_json[{index}]"),
-            })
-            .collect::<Vec<_>>();
-        edges.extend(turn_ids.iter().enumerate().map(|(index, child)| BlobEdge {
-            child: child.clone(),
-            field_name: format!("turns[{index}]"),
-        }));
-        edges.extend(todo_ids.iter().enumerate().map(|(index, child)| BlobEdge {
-            child: child.clone(),
-            field_name: format!("todos[{index}]"),
-        }));
-        if let Some(child) = plan_id {
-            edges.push(BlobEdge {
-                child,
-                field_name: "plan".into(),
-            });
-        }
-        let head = self.sync.persist(&encoded, &edges).await?;
-        if !self
-            .store
-            .publish_head(conversation_id, revision, &head)
-            .await?
-        {
-            return Err(Error::Cancelled);
-        }
-        let dependencies = self.store.blob_closure(std::slice::from_ref(&head)).await?;
-        self.store
-            .enqueue_outbox(
-                self.sync.request_id(),
-                &format!("checkpoint:{}", head.to_base64()),
-                "checkpoint",
-                &encoded,
-                &dependencies,
-            )
-            .await?;
-        Ok(checkpoint)
-    }
-
-    pub async fn publish(
-        &self,
-        handle: &RunHandle,
-        checkpoint: &pb::ConversationStateStructure,
-    ) -> Result<()> {
-        let encoded = checkpoint.encode_to_vec();
-        let head = BlobId::digest(&encoded);
-        let dependencies = self.store.blob_closure(std::slice::from_ref(&head)).await?;
-        if !self
-            .store
-            .dependencies_acked(self.sync.request_id(), &dependencies)
-            .await?
-        {
-            return Err(Error::Protocol(format!(
-                "checkpoint {} published before Blob ACK barrier",
-                head.to_base64()
-            )));
-        }
-        handle.emit(&pb::AgentServerMessage {
-            ttft_breakdown: None,
-            message: Some(
-                pb::agent_server_message::Message::ConversationCheckpointUpdate(checkpoint.clone()),
-            ),
-        })?;
-        self.store
-            .ack_outbox(
-                self.sync.request_id(),
-                &format!("checkpoint:{}", head.to_base64()),
-            )
-            .await?;
-        Ok(())
-    }
-
-    async fn build_derived_state(
-        &self,
-        messages: &[CanonicalMessage],
-    ) -> Result<(Vec<BlobId>, Option<BlobId>)> {
-        let state = fold_derived_state(messages);
-        let todo_values = state
-            .todos
-            .as_ref()
-            .and_then(|value| value.get("todos").or(Some(value)))
-            .and_then(serde_json::Value::as_array);
-        let mut todo_ids = Vec::new();
-        for todo in todo_values.into_iter().flatten() {
-            let status = match todo
-                .get("status")
-                .and_then(serde_json::Value::as_str)
-                .unwrap_or("pending")
-            {
-                "in_progress" => pb::TodoStatus::InProgress,
-                "completed" => pb::TodoStatus::Completed,
-                "cancelled" => pb::TodoStatus::Cancelled,
-                _ => pb::TodoStatus::Pending,
-            };
-            let message = pb::TodoItem {
-                id: todo
-                    .get("id")
-                    .and_then(serde_json::Value::as_str)
-                    .unwrap_or_default()
-                    .into(),
-                content: todo
-                    .get("content")
-                    .and_then(serde_json::Value::as_str)
-                    .unwrap_or_default()
-                    .into(),
-                status: status as i32,
-                created_at: 0,
-                updated_at: 0,
-                dependencies: todo
-                    .get("dependencies")
-                    .and_then(serde_json::Value::as_array)
-                    .into_iter()
-                    .flatten()
-                    .filter_map(serde_json::Value::as_str)
-                    .map(str::to_string)
-                    .collect(),
-            };
-            let mut encoded = Vec::new();
-            message.encode(&mut encoded)?;
-            todo_ids.push(self.sync.persist(&encoded, &[]).await?);
-        }
-        let plan_id = if let Some(value) = state.plan {
-            let text = value
-                .get("plan")
-                .and_then(serde_json::Value::as_str)
-                .or_else(|| value.as_str())
-                .unwrap_or_else(|| {
-                    value
-                        .get("overview")
-                        .and_then(serde_json::Value::as_str)
-                        .unwrap_or_default()
-                });
-            let mut encoded = Vec::new();
-            pb::ConversationPlan { plan: text.into() }.encode(&mut encoded)?;
-            Some(self.sync.persist(&encoded, &[]).await?)
-        } else {
-            None
-        };
-        Ok((todo_ids, plan_id))
-    }
-
-    async fn build_turns(
-        &self,
-        messages: &[CanonicalMessage],
-        mode: i32,
-        completed_overlay: &HashSet<String>,
-    ) -> Result<Vec<BlobId>> {
-        let mut completed = completed_overlay.clone();
-        for message in messages {
-            if let MessageContent::ToolResult(result) = &message.content {
-                completed.insert(result.call_id.clone());
-            }
-        }
-        let mut turns = Vec::<(CanonicalMessage, Vec<&CanonicalMessage>)>::new();
-        for message in messages {
-            if message.role == Role::User && message.origin == Origin::User {
-                turns.push((message.clone(), Vec::new()));
-            } else if matches!(message.origin, Origin::Assistant | Origin::Tool) {
-                if let Some((_, steps)) = turns.last_mut() {
-                    steps.push(message);
-                }
-            }
-        }
-        let mut turn_ids = Vec::with_capacity(turns.len());
-        for (user, step_messages) in turns {
-            let text = match user.content {
-                MessageContent::Text { text } => text,
-                other => serde_json::to_string(&other)?,
-            };
-            let user_message = pb::UserMessage {
-                text,
-                message_id: user.message_id.clone(),
-                mode,
-                ..Default::default()
-            };
-            let mut encoded = Vec::new();
-            user_message.encode(&mut encoded)?;
-            let user_id = self.sync.persist(&encoded, &[]).await?;
-            let mut step_ids = Vec::new();
-            for message in step_messages {
-                for step in message_steps(message, &completed)? {
-                    let mut encoded = Vec::new();
-                    step.encode(&mut encoded)?;
-                    step_ids.push(self.sync.persist(&encoded, &[]).await?);
-                }
-            }
-            let turn = pb::ConversationTurnStructure {
-                turn: Some(
-                    pb::conversation_turn_structure::Turn::AgentConversationTurn(
-                        pb::AgentConversationTurnStructure {
-                            user_message: user_id.as_bytes().to_vec(),
-                            steps: step_ids.iter().map(|id| id.as_bytes().to_vec()).collect(),
-                            request_id: None,
-                            encrypted_model: None,
-                            dynamic_tool_count: None,
-                            send_message_step_indices: Vec::new(),
-                        },
-                    ),
-                ),
-            };
-            let mut encoded = Vec::new();
-            turn.encode(&mut encoded)?;
-            let mut edges = vec![BlobEdge {
-                child: user_id,
-                field_name: "agent_conversation_turn.user_message".into(),
-            }];
-            edges.extend(
-                step_ids
-                    .into_iter()
-                    .enumerate()
-                    .map(|(index, child)| BlobEdge {
-                        child,
-                        field_name: format!("agent_conversation_turn.steps[{index}]"),
-                    }),
-            );
-            turn_ids.push(self.sync.persist(&encoded, &edges).await?);
-        }
-        Ok(turn_ids)
-    }
-
-    pub async fn import_prefetched(&self, blobs: &[pb::PreFetchedBlob]) -> Result<()> {
-        for blob in blobs {
-            let expected = BlobId::from_bytes(&blob.id)?;
-            let actual = self.store.put_blob(&blob.value, &[]).await?;
-            if expected != actual {
-                return Err(Error::Protocol(format!(
-                    "prefetched Blob hash mismatch: {}",
-                    expected.to_base64()
-                )));
-            }
-        }
-        Ok(())
-    }
-
-    pub async fn hydrate_messages(
-        &self,
-        state: Option<&pb::ConversationStateStructure>,
-    ) -> Result<Vec<CanonicalMessage>> {
-        let mut messages = Vec::new();
-        let Some(state) = state else {
-            return Ok(messages);
-        };
-        for raw_id in &state.root_prompt_messages_json {
-            let id = BlobId::from_bytes(raw_id)?;
-            let Some(data) = self.sync.get(&id).await? else {
-                return Err(Error::Protocol(format!(
-                    "missing message Blob {}",
-                    id.to_base64()
-                )));
-            };
-            messages.push(serde_json::from_slice(&data)?);
-        }
-        Ok(messages)
-    }
-}
-
-fn message_steps(
-    message: &CanonicalMessage,
-    completed: &HashSet<String>,
-) -> Result<Vec<pb::ConversationStep>> {
-    use pb::conversation_step::Message;
-    match &message.content {
-        MessageContent::Assistant {
-            text,
-            thinking,
-            tool_calls,
-            ..
-        } => {
-            let mut steps = Vec::new();
-            if !thinking.is_empty() {
-                steps.push(pb::ConversationStep {
-                    message: Some(Message::ThinkingMessage(pb::ThinkingMessage {
-                        text: thinking.clone(),
-                        duration_ms: 0,
-                    })),
-                });
-            }
-            if !text.is_empty() {
-                steps.push(pb::ConversationStep {
-                    message: Some(Message::AssistantMessage(pb::AssistantMessage {
-                        text: text.clone(),
-                    })),
-                });
-            }
-            for call in tool_calls {
-                let tool = render_tool_call(
-                    &ToolCall {
-                        index: 0,
-                        call_id: call.call_id.clone(),
-                        model_call_id: String::new(),
-                        name: call.name.clone(),
-                        arguments_text: serde_json::to_string(&call.arguments).unwrap_or_default(),
-                        arguments: call.arguments.clone(),
-                    },
-                    completed.contains(&call.call_id),
-                )?;
-                steps.push(pb::ConversationStep {
-                    message: Some(Message::ToolCall(tool)),
-                });
-            }
-            Ok(steps)
-        }
-        _ => Ok(Vec::new()),
-    }
-}

cursor-server/src/cursor/checkpoint/derived.rs

@@ -0,0 +1,226 @@
+use std::collections::HashMap;
+
+use prost::Message;
+
+use crate::{
+    cursor::{prompting::fold_derived_state, proto::agent::v1 as pb},
+    model::{CanonicalMessage, MessageContent},
+    store::BlobId,
+    Error, Result,
+};
+
+use super::CheckpointBuilder;
+
+impl CheckpointBuilder {
+    pub(super) async fn build_derived_state(
+        &self,
+        messages: &[CanonicalMessage],
+    ) -> Result<(Vec<BlobId>, Option<BlobId>)> {
+        let state = fold_derived_state(messages);
+        let todo_values = state
+            .todos
+            .as_ref()
+            .map(|value| {
+                value
+                    .get("todos")
+                    .and_then(serde_json::Value::as_array)
+                    .ok_or_else(|| Error::Protocol("TodoWrite state is missing todos[]".into()))
+            })
+            .transpose()?;
+        let mut todo_ids = Vec::new();
+        for (index, todo) in todo_values.into_iter().flatten().enumerate() {
+            let status = match todo
+                .get("status")
+                .and_then(serde_json::Value::as_str)
+                .ok_or_else(|| Error::Protocol("TodoWrite item is missing status".into()))?
+            {
+                "in_progress" => pb::TodoStatus::InProgress,
+                "completed" => pb::TodoStatus::Completed,
+                "cancelled" => pb::TodoStatus::Cancelled,
+                "pending" => pb::TodoStatus::Pending,
+                status => {
+                    return Err(Error::Protocol(format!(
+                        "unknown TodoWrite status: {status}"
+                    )))
+                }
+            };
+            let message = pb::TodoItem {
+                id: todo
+                    .get("id")
+                    .and_then(serde_json::Value::as_str)
+                    .ok_or_else(|| Error::Protocol("TodoWrite item is missing id".into()))?
+                    .into(),
+                content: todo
+                    .get("content")
+                    .and_then(serde_json::Value::as_str)
+                    .ok_or_else(|| Error::Protocol("TodoWrite item is missing content".into()))?
+                    .into(),
+                status: status as i32,
+                created_at: 0,
+                updated_at: 0,
+                dependencies: todo
+                    .get("dependencies")
+                    .and_then(serde_json::Value::as_array)
+                    .into_iter()
+                    .flatten()
+                    .filter_map(serde_json::Value::as_str)
+                    .map(str::to_string)
+                    .collect(),
+            };
+            let mut encoded = Vec::new();
+            message.encode(&mut encoded)?;
+            let id = BlobId::digest(&encoded);
+            if self.base.todos.get(index).map(|raw| raw.as_slice()) == Some(id.as_bytes()) {
+                todo_ids.push(id);
+            } else {
+                todo_ids.push(self.sync.persist(&encoded, &[]).await?);
+            }
+        }
+        let plan_id = if let Some(value) = state.plan {
+            let text = value
+                .get("plan")
+                .and_then(serde_json::Value::as_str)
+                .or_else(|| value.as_str())
+                .or_else(|| value.get("overview").and_then(serde_json::Value::as_str))
+                .ok_or_else(|| Error::Protocol("plan state has no textual plan".into()))?;
+            let mut encoded = Vec::new();
+            pb::ConversationPlan { plan: text.into() }.encode(&mut encoded)?;
+            let id = BlobId::digest(&encoded);
+            if self.base.plan.as_deref() == Some(id.as_bytes()) {
+                Some(id)
+            } else {
+                Some(self.sync.persist(&encoded, &[]).await?)
+            }
+        } else {
+            None
+        };
+        Ok((todo_ids, plan_id))
+    }
+}
+
+pub(super) fn update_current_step_state(
+    messages: &[CanonicalMessage],
+) -> Option<pb::CommunicateUpdateTurnState> {
+    let result_indices = messages
+        .iter()
+        .filter_map(|message| match &message.content {
+            MessageContent::ToolResult(result) => {
+                update_message_index(&result.content).map(|index| (result.call_id.as_str(), index))
+            }
+            _ => None,
+        })
+        .collect::<HashMap<_, _>>();
+    let mut state = pb::CommunicateUpdateTurnState::default();
+    for message in messages {
+        let MessageContent::Assistant { tool_calls, .. } = &message.content else {
+            continue;
+        };
+        for call in tool_calls {
+            if normalize(&call.name) != "updatecurrentstep" {
+                continue;
+            }
+            if let (Some(step), Some(message_index)) = (
+                call.arguments
+                    .get("current_step")
+                    .and_then(serde_json::Value::as_str),
+                result_indices.get(call.call_id.as_str()),
+            ) {
+                state.history.push(pb::CommunicateUpdateHistoryEntry {
+                    step: step.into(),
+                    message_index: *message_index,
+                });
+            }
+            if let Some(summary) = call
+                .arguments
+                .get("final_summary")
+                .and_then(serde_json::Value::as_str)
+            {
+                state.final_summary = Some(summary.into());
+            }
+            if let Some(subtitle) = call
+                .arguments
+                .get("completed_subtitle")
+                .and_then(serde_json::Value::as_str)
+            {
+                state.completed_subtitle = Some(subtitle.into());
+            }
+        }
+    }
+    (!state.history.is_empty()
+        || state.final_summary.is_some()
+        || state.completed_subtitle.is_some())
+    .then_some(state)
+}
+
+fn update_message_index(output: &str) -> Option<u32> {
+    let value: serde_json::Value = serde_json::from_str(output).ok()?;
+    value
+        .get("success")
+        .and_then(|success| success.get("message_index"))
+        .and_then(serde_json::Value::as_u64)
+        .and_then(|index| u32::try_from(index).ok())
+}
+
+fn normalize(name: &str) -> String {
+    name.chars()
+        .filter(|character| character.is_ascii_alphanumeric())
+        .flat_map(char::to_lowercase)
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::model::{Origin, Role, ToolCallContent, ToolResultContent};
+
+    #[test]
+    fn update_current_step_is_folded_from_canonical_messages() {
+        let messages = vec![
+            CanonicalMessage {
+                message_id: "assistant".into(),
+                role: Role::Assistant,
+                origin: Origin::Assistant,
+                content: MessageContent::Assistant {
+                    text: String::new(),
+                    thinking: String::new(),
+                    tool_round_id: Some("round".into()),
+                    replay_state: None,
+                    tool_calls: vec![ToolCallContent {
+                        index: 0,
+                        call_id: "call".into(),
+                        name: "UpdateCurrentStep".into(),
+                        arguments: serde_json::json!({
+                            "current_step": "Inspecting protocol",
+                            "final_summary": "Protocol verified.",
+                            "completed_subtitle": "Verified protocol flow"
+                        }),
+                    }],
+                },
+                runtime_event_id: None,
+            },
+            CanonicalMessage {
+                message_id: "result".into(),
+                role: Role::Tool,
+                origin: Origin::Tool,
+                content: MessageContent::ToolResult(ToolResultContent {
+                    call_id: "call".into(),
+                    name: "UpdateCurrentStep".into(),
+                    content: serde_json::json!({
+                        "success": {"current_step": "Inspecting protocol", "message_index": 3}
+                    })
+                    .to_string(),
+                    is_error: false,
+                }),
+                runtime_event_id: None,
+            },
+        ];
+        let state = update_current_step_state(&messages).unwrap();
+        assert_eq!(state.history[0].step, "Inspecting protocol");
+        assert_eq!(state.history[0].message_index, 3);
+        assert_eq!(state.final_summary.as_deref(), Some("Protocol verified."));
+        assert_eq!(
+            state.completed_subtitle.as_deref(),
+            Some("Verified protocol flow")
+        );
+    }
+}

cursor-server/src/cursor/checkpoint/mod.rs

@@ -0,0 +1,223 @@
+mod derived;
+mod recovery;
+mod roots;
+mod turns;
+pub(crate) mod worker;
+
+use std::collections::HashSet;
+
+use crate::{
+    cursor::{
+        blob_sync::BlobSynchronizer, presentation::PresentationDelta, projection,
+        proto::agent::v1 as pb, CursorSessionHandle,
+    },
+    model::{CanonicalMessage, ToolCall, ToolDefinition, ToolRoundAssistant},
+    store::Store,
+    Result,
+};
+
+use roots::RootFrontier;
+use turns::TurnFrontier;
+
+#[derive(Clone)]
+pub struct CheckpointBuilder {
+    store: Store,
+    sync: BlobSynchronizer,
+    parent_tool_call_id: Option<String>,
+    base: pb::ConversationStateStructure,
+    model: String,
+    max_context_tokens: Option<u64>,
+    instructions: String,
+    tool_definitions: Vec<ToolDefinition>,
+    allowed_tools: Vec<String>,
+    dynamic_tools: HashSet<String>,
+    turn_user: Option<pb::UserMessage>,
+    roots: Option<RootFrontier>,
+    turn: Option<TurnFrontier>,
+    turns_initialized: bool,
+}
+
+impl CheckpointBuilder {
+    pub fn new(
+        store: Store,
+        sync: BlobSynchronizer,
+        parent_tool_call_id: Option<String>,
+        base: Option<pb::ConversationStateStructure>,
+    ) -> Self {
+        Self {
+            store,
+            sync,
+            parent_tool_call_id,
+            base: base.unwrap_or_default(),
+            model: String::new(),
+            max_context_tokens: None,
+            instructions: String::new(),
+            tool_definitions: Vec::new(),
+            allowed_tools: Vec::new(),
+            dynamic_tools: HashSet::new(),
+            turn_user: None,
+            roots: None,
+            turn: None,
+            turns_initialized: false,
+        }
+    }
+
+    pub fn configure(
+        &mut self,
+        model: String,
+        max_context_tokens: Option<u64>,
+        instructions: String,
+        tool_definitions: Vec<ToolDefinition>,
+        dynamic_tools: HashSet<String>,
+        turn_user: Option<pb::UserMessage>,
+    ) {
+        self.model = model;
+        self.max_context_tokens = max_context_tokens;
+        self.instructions = instructions;
+        self.allowed_tools = tool_definitions
+            .iter()
+            .map(|tool| tool.name.clone())
+            .collect();
+        self.tool_definitions = tool_definitions;
+        self.dynamic_tools = dynamic_tools;
+        self.turn_user = turn_user;
+    }
+
+    pub(crate) fn record_context_tokens(&mut self, used_tokens: Option<u64>) {
+        let Some(used_tokens) = used_tokens else {
+            return;
+        };
+        let max_tokens = self
+            .base
+            .token_details
+            .as_ref()
+            .map(|details| details.max_tokens as u64)
+            .filter(|tokens| *tokens != 0)
+            .or(self.max_context_tokens);
+        let Some(max_tokens) = max_tokens else {
+            return;
+        };
+        let details = self.base.token_details.get_or_insert_with(Default::default);
+        details.used_tokens = used_tokens.min(u32::MAX as u64) as u32;
+        details.max_tokens = max_tokens.min(u32::MAX as u64) as u32;
+        details.prompt_context_usage_tree = None;
+        details.prompt_context_usage_snapshot_blob_id = None;
+    }
+
+    pub async fn settled(
+        &mut self,
+        messages: &[CanonicalMessage],
+        mode: i32,
+        presentation: &PresentationDelta,
+    ) -> Result<pb::ConversationStateStructure> {
+        self.build_state(messages, mode, Vec::new(), presentation)
+            .await
+    }
+
+    pub async fn staged_tool_round(
+        &mut self,
+        stable_messages: &[CanonicalMessage],
+        mode: i32,
+        assistant: &ToolRoundAssistant,
+        calls: &[ToolCall],
+        started_at_ms: u64,
+        presentation: &PresentationDelta,
+    ) -> Result<pb::ConversationStateStructure> {
+        let pending = projection::staged_tool_round(
+            assistant,
+            calls,
+            &self.model,
+            &self.allowed_tools,
+            &self.dynamic_tools,
+            started_at_ms,
+        )?;
+        self.build_state(stable_messages, mode, vec![pending], presentation)
+            .await
+    }
+
+    pub async fn staged_final(
+        &mut self,
+        stable_messages: &[CanonicalMessage],
+        mode: i32,
+        assistant: &CanonicalMessage,
+        started_at_ms: u64,
+        presentation: &PresentationDelta,
+    ) -> Result<pb::ConversationStateStructure> {
+        let pending = projection::staged_final(
+            assistant,
+            &self.model,
+            &self.allowed_tools,
+            &self.dynamic_tools,
+            started_at_ms,
+        )?;
+        self.build_state(stable_messages, mode, vec![pending], presentation)
+            .await
+    }
+
+    async fn build_state(
+        &mut self,
+        messages: &[CanonicalMessage],
+        mode: i32,
+        pending_tool_calls: Vec<String>,
+        presentation: &PresentationDelta,
+    ) -> Result<pb::ConversationStateStructure> {
+        let root_ids = self.project_roots(messages).await?;
+        let turn_ids = self.project_turns(mode, presentation).await?;
+        let (todo_ids, plan_id) = self.build_derived_state(messages).await?;
+        self.base.todos = todo_ids.iter().map(|id| id.as_bytes().to_vec()).collect();
+        self.base.plan = plan_id.as_ref().map(|id| id.as_bytes().to_vec());
+        let communicate_update_states_by_parent_tool_call_id = self
+            .parent_tool_call_id
+            .as_ref()
+            .and_then(|parent| {
+                derived::update_current_step_state(messages).map(|state| (parent.clone(), state))
+            })
+            .into_iter()
+            .collect();
+
+        for path in &presentation.read_paths {
+            if !self.base.read_paths.contains(path) {
+                self.base.read_paths.push(path.clone());
+            }
+        }
+        let mut checkpoint = self.base.clone();
+        checkpoint.root_prompt_messages_json =
+            root_ids.iter().map(|id| id.as_bytes().to_vec()).collect();
+        checkpoint.turns = turn_ids.iter().map(|id| id.as_bytes().to_vec()).collect();
+        checkpoint.pending_tool_calls = pending_tool_calls;
+        checkpoint.mode = Some(mode);
+        checkpoint.communicate_update_states_by_parent_tool_call_id =
+            communicate_update_states_by_parent_tool_call_id;
+        if let Some(details) = checkpoint.token_details.as_mut() {
+            details.breakdown = Some(crate::cursor::usage::breakdown(
+                details.used_tokens,
+                details.max_tokens,
+                details.breakdown.as_ref(),
+                &self.instructions,
+                &self.tool_definitions,
+                &self.dynamic_tools,
+                messages,
+            )?);
+        }
+        Ok(checkpoint)
+    }
+
+    pub async fn publish(
+        &self,
+        handle: &CursorSessionHandle,
+        checkpoint: &pb::ConversationStateStructure,
+    ) -> Result<()> {
+        tracing::debug!(
+            request_id = self.sync.request_id(),
+            stable_roots = checkpoint.root_prompt_messages_json.len(),
+            pending_assistants = checkpoint.pending_tool_calls.len(),
+            "publishing Cursor checkpoint"
+        );
+        handle.emit(&pb::AgentServerMessage {
+            ttft_breakdown: None,
+            message: Some(
+                pb::agent_server_message::Message::ConversationCheckpointUpdate(checkpoint.clone()),
+            ),
+        })
+    }
+}

cursor-server/src/cursor/checkpoint/recovery.rs

@@ -0,0 +1,48 @@
+use crate::{
+    cursor::{projection, proto::agent::v1 as pb},
+    model::CanonicalMessage,
+    store::BlobId,
+    Error, Result,
+};
+
+use super::CheckpointBuilder;
+
+impl CheckpointBuilder {
+    pub async fn import_prefetched(&self, blobs: &[pb::PreFetchedBlob]) -> Result<()> {
+        for blob in blobs {
+            let expected = BlobId::from_bytes(&blob.id)?;
+            let actual = self.store.put_blob(&blob.value, &[]).await?;
+            if expected != actual {
+                return Err(Error::Protocol(format!(
+                    "prefetched Blob hash mismatch: {}",
+                    expected.to_base64()
+                )));
+            }
+        }
+        Ok(())
+    }
+
+    pub async fn hydrate_messages(
+        &self,
+        state: Option<&pb::ConversationStateStructure>,
+    ) -> Result<Vec<CanonicalMessage>> {
+        let mut messages = Vec::new();
+        let Some(state) = state else {
+            return Ok(messages);
+        };
+        for (ordinal, raw_id) in state.root_prompt_messages_json.iter().enumerate() {
+            let id = BlobId::from_bytes(raw_id)?;
+            let Some(data) = self.sync.get(&id).await? else {
+                return Err(Error::Protocol(format!(
+                    "missing message Blob {}",
+                    id.to_base64()
+                )));
+            };
+            messages.push(projection::decode(
+                &data,
+                format!("cursor-root:{}:{ordinal}", id.to_base64()),
+            )?);
+        }
+        Ok(messages)
+    }
+}

cursor-server/src/cursor/checkpoint/roots.rs

@@ -0,0 +1,106 @@
+use crate::{cursor::projection, model::CanonicalMessage, store::BlobId, Error, Result};
+
+use super::CheckpointBuilder;
+
+#[derive(Clone)]
+pub(super) struct RootFrontier {
+    pub(super) ids: Vec<BlobId>,
+    pub(super) generated: Vec<Vec<u8>>,
+    pub(super) base_count: usize,
+}
+
+impl CheckpointBuilder {
+    pub(super) async fn project_roots(
+        &mut self,
+        messages: &[CanonicalMessage],
+    ) -> Result<Vec<BlobId>> {
+        let wire_messages = projection::stable_messages(&self.instructions, messages, &self.model)?;
+        self.ensure_roots()?;
+        let replacement = self
+            .roots
+            .as_ref()
+            .and_then(|roots| changed_system_root(roots, &wire_messages));
+        if let Some(message) = replacement {
+            let id = self.sync.persist(&message, &[]).await?;
+            self.roots
+                .as_mut()
+                .ok_or_else(|| Error::Protocol("Cursor root frontier was not initialized".into()))?
+                .ids[0] = id;
+        }
+        let roots = self
+            .roots
+            .as_mut()
+            .ok_or_else(|| Error::Protocol("Cursor root frontier was not initialized".into()))?;
+        if wire_messages.len() < roots.ids.len() {
+            return Err(Error::Protocol(format!(
+                "Cursor stable history shrank from {} to {} roots",
+                roots.ids.len(),
+                wire_messages.len()
+            )));
+        }
+        for (index, expected) in roots.generated.iter().enumerate() {
+            let wire_index = roots.base_count + index;
+            if wire_messages.get(wire_index) != Some(expected) {
+                return Err(Error::Protocol(format!(
+                    "Cursor stable root changed at index {wire_index}"
+                )));
+            }
+        }
+        for message in wire_messages.iter().skip(roots.ids.len()) {
+            roots.ids.push(self.sync.persist(message, &[]).await?);
+            roots.generated.push(message.clone());
+        }
+        Ok(roots.ids.clone())
+    }
+
+    fn ensure_roots(&mut self) -> Result<()> {
+        if self.roots.is_some() {
+            return Ok(());
+        }
+        let ids = self
+            .base
+            .root_prompt_messages_json
+            .iter()
+            .map(|id| BlobId::from_bytes(id))
+            .collect::<Result<Vec<_>>>()?;
+        self.roots = Some(RootFrontier {
+            base_count: ids.len(),
+            ids,
+            generated: Vec::new(),
+        });
+        Ok(())
+    }
+}
+
+fn changed_system_root(roots: &RootFrontier, messages: &[Vec<u8>]) -> Option<Vec<u8>> {
+    roots
+        .ids
+        .first()
+        .zip(messages.first())
+        .filter(|(current, message)| **current != BlobId::digest(message))
+        .map(|(_, message)| message.clone())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn a_new_prompt_replaces_only_the_system_root() {
+        let previous = b"previous prompt".to_vec();
+        let current = b"current prompt".to_vec();
+        let roots = RootFrontier {
+            ids: vec![BlobId::digest(&previous), BlobId::digest(b"user")],
+            generated: Vec::new(),
+            base_count: 2,
+        };
+        assert_eq!(
+            changed_system_root(&roots, &[current.clone(), b"user".to_vec()]),
+            Some(current)
+        );
+        assert_eq!(
+            changed_system_root(&roots, &[previous, b"user".to_vec()]),
+            None
+        );
+    }
+}

cursor-server/src/cursor/checkpoint/turns.rs

@@ -0,0 +1,126 @@
+use prost::Message;
+
+use crate::{
+    cursor::{presentation::PresentationDelta, proto::agent::v1 as pb},
+    store::{BlobEdge, BlobId},
+    Error, Result,
+};
+
+use super::CheckpointBuilder;
+
+#[derive(Clone)]
+pub(super) struct TurnFrontier {
+    pub(super) preceding: Vec<BlobId>,
+    pub(super) current_id: Option<BlobId>,
+    pub(super) current: pb::AgentConversationTurnStructure,
+}
+
+impl CheckpointBuilder {
+    pub(super) async fn project_turns(
+        &mut self,
+        mode: i32,
+        presentation: &PresentationDelta,
+    ) -> Result<Vec<BlobId>> {
+        self.ensure_turn(mode).await?;
+        let Some(turn) = self.turn.as_mut() else {
+            return self
+                .base
+                .turns
+                .iter()
+                .map(|id| BlobId::from_bytes(id))
+                .collect();
+        };
+        let changed = !presentation.steps.is_empty();
+        for step in &presentation.steps {
+            let mut encoded = Vec::new();
+            step.encode(&mut encoded)?;
+            let id = self.sync.persist(&encoded, &[]).await?;
+            turn.current.steps.push(id.as_bytes().to_vec());
+        }
+        if changed || turn.current_id.is_none() {
+            let wrapper = pb::ConversationTurnStructure {
+                turn: Some(
+                    pb::conversation_turn_structure::Turn::AgentConversationTurn(
+                        turn.current.clone(),
+                    ),
+                ),
+            };
+            let mut encoded = Vec::new();
+            wrapper.encode(&mut encoded)?;
+            let mut edges = Vec::with_capacity(turn.current.steps.len() + 1);
+            edges.push(BlobEdge {
+                child: BlobId::from_bytes(&turn.current.user_message)?,
+                field_name: "agent_conversation_turn.user_message".into(),
+            });
+            for (index, raw_id) in turn.current.steps.iter().enumerate() {
+                edges.push(BlobEdge {
+                    child: BlobId::from_bytes(raw_id)?,
+                    field_name: format!("agent_conversation_turn.steps[{index}]"),
+                });
+            }
+            turn.current_id = Some(self.sync.persist(&encoded, &edges).await?);
+        }
+        let mut ids = turn.preceding.clone();
+        ids.push(
+            turn.current_id
+                .clone()
+                .ok_or_else(|| Error::Protocol("Cursor current Turn has no BlobID".into()))?,
+        );
+        Ok(ids)
+    }
+
+    async fn ensure_turn(&mut self, mode: i32) -> Result<()> {
+        if self.turns_initialized {
+            return Ok(());
+        }
+        self.turns_initialized = true;
+        let base_ids = self
+            .base
+            .turns
+            .iter()
+            .map(|id| BlobId::from_bytes(id))
+            .collect::<Result<Vec<_>>>()?;
+        if let Some(mut user) = self.turn_user.clone() {
+            user.mode = mode;
+            let mut encoded = Vec::new();
+            user.encode(&mut encoded)?;
+            let user_id = self.sync.persist(&encoded, &[]).await?;
+            self.turn = Some(TurnFrontier {
+                preceding: base_ids,
+                current_id: None,
+                current: pb::AgentConversationTurnStructure {
+                    user_message: user_id.as_bytes().to_vec(),
+                    steps: Vec::new(),
+                    request_id: Some(self.sync.request_id().into()),
+                    encrypted_model: None,
+                    dynamic_tool_count: None,
+                    send_message_step_indices: Vec::new(),
+                },
+            });
+            return Ok(());
+        }
+        let Some((current_id, preceding)) = base_ids.split_last() else {
+            return Ok(());
+        };
+        let data = self.sync.get(current_id).await?.ok_or_else(|| {
+            Error::Protocol(format!(
+                "missing current Turn Blob {}",
+                current_id.to_base64()
+            ))
+        })?;
+        let wrapper = pb::ConversationTurnStructure::decode(data.as_slice())?;
+        let Some(pb::conversation_turn_structure::Turn::AgentConversationTurn(current)) =
+            wrapper.turn
+        else {
+            return Err(Error::Protocol(
+                "current Cursor Turn is not an agent conversation turn".into(),
+            ));
+        };
+        self.turn = Some(TurnFrontier {
+            preceding: preceding.to_vec(),
+            current_id: Some(current_id.clone()),
+            current,
+        });
+        Ok(())
+    }
+}

cursor-server/src/cursor/checkpoint/worker.rs

@@ -0,0 +1,181 @@
+use tokio::sync::{mpsc, oneshot};
+
+use crate::{
+    cursor::{presentation::PresentationDelta, proto::agent::v1 as pb, CursorSessionHandle},
+    model::{RevisionId, ToolRoundId},
+    store::Store,
+    Error, Result,
+};
+
+use super::CheckpointBuilder;
+
+pub(crate) struct CheckpointJob {
+    pub kind: CheckpointKind,
+    pub presentation: PresentationDelta,
+    pub context_tokens: Option<u64>,
+    pub ready: Option<oneshot::Sender<std::result::Result<(), String>>>,
+}
+
+pub(crate) enum CheckpointKind {
+    Settled(RevisionId),
+    ToolStarted {
+        round_id: ToolRoundId,
+        stable_revision_id: RevisionId,
+    },
+    ToolSettled(RevisionId),
+    Final {
+        revision_id: RevisionId,
+        result: oneshot::Sender<Result<FinalCheckpoints>>,
+    },
+}
+
+pub(crate) struct FinalCheckpoints {
+    pub staged: pb::ConversationStateStructure,
+    pub settled: pb::ConversationStateStructure,
+}
+
+pub(crate) struct CheckpointWorker {
+    pub jobs: mpsc::Sender<CheckpointJob>,
+    pub failures: mpsc::Receiver<Error>,
+    task: tokio::task::JoinHandle<()>,
+}
+
+impl CheckpointWorker {
+    pub fn spawn(
+        store: Store,
+        mut builder: CheckpointBuilder,
+        handle: CursorSessionHandle,
+        mode: i32,
+    ) -> Self {
+        let (jobs, mut receiver) = mpsc::channel::<CheckpointJob>(32);
+        let (failures, failure_receiver) = mpsc::channel(1);
+        let task = tokio::spawn(async move {
+            while let Some(job) = receiver.recv().await {
+                builder.record_context_tokens(job.context_tokens);
+                let presentation = job.presentation;
+                let ready = job.ready;
+                let result = match job.kind {
+                    CheckpointKind::Settled(revision_id)
+                    | CheckpointKind::ToolSettled(revision_id) => {
+                        publish_settled(
+                            &store,
+                            &mut builder,
+                            &handle,
+                            mode,
+                            revision_id,
+                            &presentation,
+                        )
+                        .await
+                    }
+                    CheckpointKind::ToolStarted {
+                        round_id,
+                        stable_revision_id,
+                    } => {
+                        publish_started(
+                            &store,
+                            &mut builder,
+                            &handle,
+                            mode,
+                            round_id,
+                            stable_revision_id,
+                            &presentation,
+                        )
+                        .await
+                    }
+                    CheckpointKind::Final {
+                        revision_id,
+                        result,
+                    } => {
+                        let checkpoints =
+                            build_final(&store, &mut builder, mode, revision_id, &presentation)
+                                .await;
+                        let _ = result.send(checkpoints);
+                        Ok(())
+                    }
+                };
+
+                if let Err(error) = result {
+                    if let Some(ready) = ready {
+                        let _ = ready.send(Err(error.to_string()));
+                    }
+                    tracing::error!(%error, "failed to build or publish Cursor checkpoint");
+                    let _ = failures.send(error).await;
+                    break;
+                }
+                if let Some(ready) = ready {
+                    let _ = ready.send(Ok(()));
+                }
+            }
+        });
+        Self {
+            jobs,
+            failures: failure_receiver,
+            task,
+        }
+    }
+
+    pub fn abort(&self) {
+        self.task.abort();
+    }
+}
+
+async fn publish_settled(
+    store: &Store,
+    builder: &mut CheckpointBuilder,
+    handle: &CursorSessionHandle,
+    mode: i32,
+    revision_id: RevisionId,
+    presentation: &PresentationDelta,
+) -> Result<()> {
+    let messages = store.load_revision_messages(revision_id).await?;
+    let checkpoint = builder.settled(&messages, mode, presentation).await?;
+    builder.publish(handle, &checkpoint).await
+}
+
+async fn publish_started(
+    store: &Store,
+    builder: &mut CheckpointBuilder,
+    handle: &CursorSessionHandle,
+    mode: i32,
+    round_id: ToolRoundId,
+    stable_revision_id: RevisionId,
+    presentation: &PresentationDelta,
+) -> Result<()> {
+    let round = store
+        .tool_round(&round_id)
+        .await?
+        .ok_or_else(|| Error::Store(format!("checkpoint tool round not found: {round_id}")))?;
+    let messages = store.load_revision_messages(stable_revision_id).await?;
+    let checkpoint = builder
+        .staged_tool_round(
+            &messages,
+            mode,
+            &round.assistant,
+            &round.calls,
+            round.created_at_ms,
+            presentation,
+        )
+        .await?;
+    builder.publish(handle, &checkpoint).await
+}
+
+async fn build_final(
+    store: &Store,
+    builder: &mut CheckpointBuilder,
+    mode: i32,
+    revision_id: RevisionId,
+    presentation: &PresentationDelta,
+) -> Result<FinalCheckpoints> {
+    let messages = store.load_revision_messages(revision_id).await?;
+    let (assistant, stable) = messages
+        .split_last()
+        .ok_or_else(|| Error::Store("final revision contains no assistant".into()))?;
+    let started_at_ms = crate::cursor::tools::runtime::now_ms();
+    let staged = builder
+        .staged_final(stable, mode, assistant, started_at_ms, presentation)
+        .await?;
+    let settled = builder
+        .settled(&messages, mode, &PresentationDelta::default())
+        .await?;
+    Ok(FinalCheckpoints { staged, settled })
+}

cursor-server/src/cursor/command.rs

@@ -0,0 +1,11 @@
+use crate::cursor::proto::agent::v1 as pb;
+
+#[derive(Debug)]
+pub enum CursorCommand {
+    Append {
+        seqno: i64,
+        message: Box<pb::AgentClientMessage>,
+    },
+    Abort,
+    Finished,
+}

cursor-server/src/cursor/connect.rs

@@ -94,7 +94,7 @@ fn encode_end_stream_payload(payload: &[u8]) -> Bytes {
 pub fn decode_unary<M: Message + Default>(body: &[u8]) -> Result<M> {
     if body.len() >= 5 {
         let flags = body[0];
-        let length = u32::from_be_bytes(body[1..5].try_into().expect("four bytes")) as usize;
+        let length = u32::from_be_bytes([body[1], body[2], body[3], body[4]]) as usize;
         if flags & END_STREAM_FLAG == 0 && length == body.len() - 5 {
             return Ok(M::decode(&body[5..])?);
         }
@@ -109,7 +109,7 @@ pub fn decode_frames(mut body: &[u8]) -> Result<Vec<(u8, Bytes)>> {
             return Err(Error::Protocol("truncated Connect envelope".into()));
         }
         let flags = body[0];
-        let length = u32::from_be_bytes(body[1..5].try_into().expect("four bytes")) as usize;
+        let length = u32::from_be_bytes([body[1], body[2], body[3], body[4]]) as usize;
         body = &body[5..];
         if body.len() < length {
             return Err(Error::Protocol("truncated Connect payload".into()));

cursor-server/src/cursor/exec.rs

@@ -1,535 +0,0 @@
-use serde_json::{Map, Value};
-
-use crate::{
-    cursor::{
-        pending::{ExecContext, PendingExecRegistry},
-        proto::agent::v1 as pb,
-        tool_result::ToolCompletion,
-    },
-    model::ToolCall,
-    Error, Result,
-};
-
-pub fn request(id: u32, call: &ToolCall, context: &ExecContext) -> Result<pb::AgentServerMessage> {
-    use pb::exec_server_message::Message;
-    let string = |name: &str| {
-        call.arguments
-            .get(name)
-            .and_then(Value::as_str)
-            .map(str::to_string)
-            .ok_or_else(|| Error::Protocol(format!("{} is missing {name}", call.name)))
-    };
-    let optional_string = |name: &str| {
-        call.arguments
-            .get(name)
-            .and_then(Value::as_str)
-            .map(str::to_string)
-    };
-    let int = |name: &str| {
-        call.arguments
-            .get(name)
-            .and_then(Value::as_i64)
-            .map(|v| v as i32)
-    };
-    let message = match normalize(&call.name).as_str() {
-        "shell" => Message::ShellStreamArgs(pb::ShellArgs {
-            command: string("command")?,
-            working_directory: optional_string("working_directory").unwrap_or_default(),
-            timeout: shell_timeout(call)?,
-            tool_call_id: call.call_id.clone(),
-            file_output_threshold_bytes: Some(40_000),
-            timeout_behavior: pb::TimeoutBehavior::Background as i32,
-            hard_timeout: Some(86_400_000),
-            description: optional_string("description"),
-            close_stdin: true,
-            conversation_id: Some(context.conversation_id.clone()),
-            admin_command_denylist: context.admin_command_denylist.clone(),
-            ..Default::default()
-        }),
-        "forcebackgroundshell" => Message::ForceBackgroundShellArgs(pb::ForceBackgroundShellArgs {
-            tool_call_id: string("tool_call_id")?,
-        }),
-        "read" => Message::ReadArgs(pb::ReadArgs {
-            path: string("path")?,
-            tool_call_id: call.call_id.clone(),
-            offset: int("offset"),
-            limit: call
-                .arguments
-                .get("limit")
-                .and_then(Value::as_u64)
-                .map(|v| v as u32),
-            encoding_hint: optional_string("encoding_hint"),
-        }),
-        "write" => Message::WriteArgs(pb::WriteArgs {
-            path: string("path")?,
-            file_text: string("contents")?,
-            tool_call_id: call.call_id.clone(),
-            return_file_content_after_write: true,
-            file_bytes: Vec::new(),
-            encoding_hint: optional_string("encoding_hint"),
-        }),
-        "delete" => Message::DeleteArgs(pb::DeleteArgs {
-            path: string("path")?,
-            tool_call_id: call.call_id.clone(),
-        }),
-        "grep" => Message::GrepArgs(pb::GrepArgs {
-            pattern: string("pattern")?,
-            path: optional_string("path"),
-            glob: optional_string("glob"),
-            output_mode: optional_string("output_mode"),
-            context_before: int("context_before"),
-            context_after: int("context_after"),
-            context: int("context"),
-            case_insensitive: call
-                .arguments
-                .get("case_insensitive")
-                .and_then(Value::as_bool),
-            r#type: optional_string("type"),
-            head_limit: int("head_limit"),
-            multiline: call.arguments.get("multiline").and_then(Value::as_bool),
-            sort: optional_string("sort"),
-            sort_ascending: call
-                .arguments
-                .get("sort_ascending")
-                .and_then(Value::as_bool),
-            tool_call_id: call.call_id.clone(),
-            sandbox_policy: None,
-            offset: int("offset"),
-        }),
-        "glob" => Message::GrepArgs(pb::GrepArgs {
-            pattern: String::new(),
-            path: optional_string("target_directory"),
-            glob: optional_string("glob_pattern"),
-            output_mode: Some("files_with_matches".into()),
-            tool_call_id: call.call_id.clone(),
-            ..Default::default()
-        }),
-        "ls" => Message::LsArgs(pb::LsArgs {
-            path: string("path")?,
-            ignore: call
-                .arguments
-                .get("ignore")
-                .and_then(Value::as_array)
-                .map(|v| {
-                    v.iter()
-                        .filter_map(Value::as_str)
-                        .map(str::to_string)
-                        .collect()
-                })
-                .unwrap_or_default(),
-            tool_call_id: call.call_id.clone(),
-            sandbox_policy: None,
-            timeout_ms: call
-                .arguments
-                .get("timeout_ms")
-                .and_then(Value::as_u64)
-                .map(|v| v as u32),
-        }),
-        "readlints" => Message::DiagnosticsArgs(pb::DiagnosticsArgs {
-            path: call
-                .arguments
-                .get("paths")
-                .and_then(Value::as_array)
-                .and_then(|paths| paths.first())
-                .and_then(Value::as_str)
-                .unwrap_or_default()
-                .into(),
-            tool_call_id: call.call_id.clone(),
-        }),
-        "patchedit" => Message::PiEditArgs(pb::PiEditExecArgs {
-            path: string("path")?,
-            edits: vec![pb::PiEditReplacement {
-                old_text: string("old_string")?,
-                new_text: string("new_string")?,
-            }],
-        }),
-        "writeshellstdin" => Message::WriteShellStdinArgs(pb::WriteShellStdinArgs {
-            shell_id: call
-                .arguments
-                .get("shell_id")
-                .and_then(Value::as_u64)
-                .unwrap_or_default() as u32,
-            chars: string("chars")?,
-        }),
-        "task" => Message::SubagentArgs(pb::SubagentArgs {
-            tool_call_id: call.call_id.clone(),
-            subagent_type: string("subagent_type")?,
-            model_id: optional_string("model").unwrap_or_default(),
-            prompt: string("prompt")?,
-            readonly: call
-                .arguments
-                .get("readonly")
-                .and_then(Value::as_bool)
-                .unwrap_or(false),
-            resume_agent_id: optional_string("resume"),
-            run_in_background: Some(false),
-            continuation_config: None,
-            parent_conversation_id: None,
-            interrupt: None,
-            mode: 0,
-            fork_agent_id: None,
-            root_parent_conversation_id: None,
-            selected_context: None,
-            direct_meta_parent_child_subagent: None,
-            environment: 0,
-            cloud_base_branch: None,
-            credentials: None,
-        }),
-        "callmcptool" => Message::McpArgs(pb::McpArgs {
-            name: string("toolName")?,
-            args: call
-                .arguments
-                .get("arguments")
-                .and_then(Value::as_object)
-                .map(json_object_to_prost)
-                .unwrap_or_default(),
-            tool_call_id: call.call_id.clone(),
-            provider_identifier: optional_string("provider_identifier").unwrap_or_default(),
-            tool_name: string("toolName")?,
-            smart_mode_approval: None,
-            smart_mode_approval_only: false,
-            skip_approval: false,
-            server_identifier: string("server")?,
-        }),
-        "fetchmcpresource" => Message::ReadMcpResourceExecArgs(pb::ReadMcpResourceExecArgs {
-            server: string("server")?,
-            uri: string("uri")?,
-            download_path: optional_string("downloadPath"),
-            tool_call_id: call.call_id.clone(),
-            smart_mode_approval: None,
-        }),
-        "webfetch" => Message::FetchArgs(pb::FetchArgs {
-            url: string("url")?,
-            tool_call_id: call.call_id.clone(),
-        }),
-        other => {
-            return Err(Error::Protocol(format!(
-                "tool {other} is not executed through ExecServerMessage"
-            )))
-        }
-    };
-    Ok(pb::AgentServerMessage {
-        ttft_breakdown: None,
-        message: Some(pb::agent_server_message::Message::ExecServerMessage(
-            pb::ExecServerMessage {
-                id,
-                exec_id: call.call_id.clone(),
-                span_context: None,
-                accept_hook_additional_contexts: Some(true),
-                message: Some(message),
-            },
-        )),
-    })
-}
-
-pub fn mcp_request(
-    id: u32,
-    call: &ToolCall,
-    definition: &pb::McpToolDefinition,
-) -> Result<pb::AgentServerMessage> {
-    let args = call
-        .arguments
-        .as_object()
-        .map(json_object_to_prost)
-        .unwrap_or_default();
-    Ok(pb::AgentServerMessage {
-        ttft_breakdown: None,
-        message: Some(pb::agent_server_message::Message::ExecServerMessage(
-            pb::ExecServerMessage {
-                id,
-                exec_id: call.call_id.clone(),
-                span_context: None,
-                accept_hook_additional_contexts: None,
-                message: Some(pb::exec_server_message::Message::McpArgs(pb::McpArgs {
-                    name: definition.name.clone(),
-                    args,
-                    tool_call_id: call.call_id.clone(),
-                    provider_identifier: definition.provider_identifier.clone(),
-                    tool_name: if definition.tool_name.is_empty() {
-                        definition.name.clone()
-                    } else {
-                        definition.tool_name.clone()
-                    },
-                    smart_mode_approval: None,
-                    smart_mode_approval_only: false,
-                    skip_approval: false,
-                    server_identifier: String::new(),
-                })),
-            },
-        )),
-    })
-}
-
-pub fn abort(id: u32) -> pb::AgentServerMessage {
-    pb::AgentServerMessage {
-        ttft_breakdown: None,
-        message: Some(pb::agent_server_message::Message::ExecServerControlMessage(
-            pb::ExecServerControlMessage {
-                message: Some(pb::exec_server_control_message::Message::Abort(
-                    pb::ExecServerAbort { id },
-                )),
-            },
-        )),
-    }
-}
-
-pub enum ClientExecEvent {
-    Delta(Box<pb::AgentServerMessage>),
-    Completed(Box<ToolCompletion>),
-    Pending,
-}
-
-pub async fn client_event(
-    message: &pb::ExecClientMessage,
-    pending: &PendingExecRegistry,
-) -> Result<ClientExecEvent> {
-    let call = pending
-        .call(message.id)
-        .await
-        .ok_or_else(|| Error::Protocol(format!("unknown ExecClientMessage id: {}", message.id)))?;
-    let Some(wire_result) = &message.message else {
-        return Ok(ClientExecEvent::Pending);
-    };
-    let pb::exec_client_message::Message::ShellStream(stream) = wire_result else {
-        return complete(message.id, pending, wire_result.clone()).await;
-    };
-    use pb::shell_stream::Event;
-    let event = match &stream.event {
-        Some(Event::Stdout(stdout)) => {
-            if pending.append_stdout(message.id, &stdout.data).await {
-                ClientExecEvent::Delta(Box::new(shell_delta(&call, true, &stdout.data)))
-            } else {
-                ClientExecEvent::Pending
-            }
-        }
-        Some(Event::Stderr(stderr)) => {
-            if pending.append_stderr(message.id, &stderr.data).await {
-                ClientExecEvent::Delta(Box::new(shell_delta(&call, false, &stderr.data)))
-            } else {
-                ClientExecEvent::Pending
-            }
-        }
-        Some(Event::Start(_)) | Some(Event::HookContext(_)) => ClientExecEvent::Pending,
-        Some(Event::Exit(exit)) => {
-            let entry = take(message.id, pending).await?;
-            let result = shell_exit_result(message, exit, &entry.stdout, &entry.stderr);
-            completed(entry, pb::exec_client_message::Message::ShellResult(result))?
-        }
-        Some(Event::Backgrounded(backgrounded)) => {
-            let entry = take(message.id, pending).await?;
-            let result = shell_backgrounded_result(
-                backgrounded,
-                &entry.stdout,
-                &entry.stderr,
-                &entry.context.terminals_folder,
-            );
-            completed(entry, pb::exec_client_message::Message::ShellResult(result))?
-        }
-        Some(Event::Rejected(value)) => {
-            let result = pb::ShellResult {
-                result: Some(pb::shell_result::Result::Rejected(value.clone())),
-                ..Default::default()
-            };
-            complete(
-                message.id,
-                pending,
-                pb::exec_client_message::Message::ShellResult(result),
-            )
-            .await?
-        }
-        Some(Event::PermissionDenied(value)) => {
-            let result = pb::ShellResult {
-                result: Some(pb::shell_result::Result::PermissionDenied(value.clone())),
-                ..Default::default()
-            };
-            complete(
-                message.id,
-                pending,
-                pb::exec_client_message::Message::ShellResult(result),
-            )
-            .await?
-        }
-        Some(Event::SandboxUnsupported(value)) => {
-            let result = pb::ShellResult {
-                result: Some(pb::shell_result::Result::SpawnError(pb::ShellSpawnError {
-                    command: value.command.clone(),
-                    working_directory: value.working_directory.clone(),
-                    error: value.reason.clone(),
-                })),
-                ..Default::default()
-            };
-            complete(
-                message.id,
-                pending,
-                pb::exec_client_message::Message::ShellResult(result),
-            )
-            .await?
-        }
-        None => ClientExecEvent::Pending,
-    };
-    Ok(event)
-}
-
-async fn complete(
-    id: u32,
-    pending: &PendingExecRegistry,
-    result: pb::exec_client_message::Message,
-) -> Result<ClientExecEvent> {
-    completed(take(id, pending).await?, result)
-}
-
-async fn take(id: u32, pending: &PendingExecRegistry) -> Result<super::pending::PendingExec> {
-    pending
-        .take(id)
-        .await
-        .ok_or_else(|| Error::Protocol(format!("unknown terminal Exec id: {id}")))
-}
-
-fn completed(
-    pending: super::pending::PendingExec,
-    result: pb::exec_client_message::Message,
-) -> Result<ClientExecEvent> {
-    Ok(ClientExecEvent::Completed(Box::new(
-        super::tool_result::from_exec(pending, &result)?,
-    )))
-}
-
-fn shell_exit_result(
-    message: &pb::ExecClientMessage,
-    exit: &pb::ShellStreamExit,
-    stdout: &str,
-    stderr: &str,
-) -> pb::ShellResult {
-    let result = if exit.code == 0 && !exit.aborted {
-        pb::shell_result::Result::Success(pb::ShellSuccess {
-            working_directory: exit.cwd.clone(),
-            exit_code: exit.code as i32,
-            stdout: stdout.into(),
-            stderr: stderr.into(),
-            interleaved_output: Some(format!("{stdout}{stderr}")),
-            local_execution_time_ms: exit
-                .local_execution_time_ms
-                .or(message.local_execution_time_ms),
-            ..Default::default()
-        })
-    } else {
-        pb::shell_result::Result::Failure(pb::ShellFailure {
-            working_directory: exit.cwd.clone(),
-            exit_code: exit.code as i32,
-            stdout: stdout.into(),
-            stderr: stderr.into(),
-            interleaved_output: Some(format!("{stdout}{stderr}")),
-            abort_reason: exit.abort_reason,
-            aborted: exit.aborted,
-            local_execution_time_ms: exit
-                .local_execution_time_ms
-                .or(message.local_execution_time_ms),
-            ..Default::default()
-        })
-    };
-    pb::ShellResult {
-        result: Some(result),
-        is_background: Some(false),
-        ..Default::default()
-    }
-}
-
-fn shell_backgrounded_result(
-    backgrounded: &pb::ShellStreamBackgrounded,
-    stdout: &str,
-    stderr: &str,
-    terminals_folder: &str,
-) -> pb::ShellResult {
-    pb::ShellResult {
-        result: Some(pb::shell_result::Result::Success(pb::ShellSuccess {
-            command: backgrounded.command.clone(),
-            working_directory: backgrounded.working_directory.clone(),
-            stdout: stdout.into(),
-            stderr: stderr.into(),
-            shell_id: Some(backgrounded.shell_id),
-            pid: backgrounded.pid,
-            ms_to_wait: backgrounded.ms_to_wait,
-            background_reason: backgrounded.reason,
-            interleaved_output: Some(format!("{stdout}{stderr}")),
-            ..Default::default()
-        })),
-        is_background: Some(true),
-        terminals_folder: (!terminals_folder.is_empty()).then(|| terminals_folder.into()),
-        pid: backgrounded.pid,
-        ..Default::default()
-    }
-}
-
-fn shell_delta(call: &ToolCall, stdout: bool, content: &str) -> pb::AgentServerMessage {
-    let delta = if stdout {
-        pb::shell_tool_call_delta::Delta::Stdout(pb::ShellToolCallStdoutDelta {
-            content: content.into(),
-        })
-    } else {
-        pb::shell_tool_call_delta::Delta::Stderr(pb::ShellToolCallStderrDelta {
-            content: content.into(),
-        })
-    };
-    super::interaction::server_interaction(pb::interaction_update::Message::ToolCallDelta(
-        Box::new(pb::ToolCallDeltaUpdate {
-            call_id: call.call_id.clone(),
-            tool_call_delta: Some(Box::new(pb::ToolCallDelta {
-                delta: Some(pb::tool_call_delta::Delta::ShellToolCallDelta(
-                    pb::ShellToolCallDelta { delta: Some(delta) },
-                )),
-            })),
-            model_call_id: call.model_call_id.clone(),
-        }),
-    ))
-}
-
-fn shell_timeout(call: &ToolCall) -> Result<i32> {
-    let value = call
-        .arguments
-        .get("block_until_ms")
-        .map(|value| {
-            value
-                .as_i64()
-                .ok_or_else(|| Error::Protocol("Shell block_until_ms must be an integer".into()))
-        })
-        .transpose()?
-        .unwrap_or(30_000);
-    i32::try_from(value)
-        .ok()
-        .filter(|value| *value >= 0)
-        .ok_or_else(|| Error::Protocol("Shell block_until_ms is out of range".into()))
-}
-
-fn normalize(value: &str) -> String {
-    value
-        .chars()
-        .filter(|c| c.is_ascii_alphanumeric())
-        .flat_map(char::to_lowercase)
-        .collect()
-}
-
-pub(crate) fn json_object_to_prost(
-    value: &Map<String, Value>,
-) -> std::collections::HashMap<String, prost_types::Value> {
-    value
-        .iter()
-        .map(|(key, value)| (key.clone(), prost_value(value)))
-        .collect()
-}
-
-fn prost_value(value: &Value) -> prost_types::Value {
-    use prost_types::{value::Kind, ListValue, Struct, Value as ProstValue};
-    let kind = match value {
-        Value::Null => Kind::NullValue(0),
-        Value::Bool(v) => Kind::BoolValue(*v),
-        Value::Number(v) => Kind::NumberValue(v.as_f64().unwrap_or_default()),
-        Value::String(v) => Kind::StringValue(v.clone()),
-        Value::Array(v) => Kind::ListValue(ListValue {
-            values: v.iter().map(prost_value).collect(),
-        }),
-        Value::Object(v) => Kind::StructValue(Struct {
-            fields: json_object_to_prost(v).into_iter().collect(),
-        }),
-    };
-    ProstValue { kind: Some(kind) }
-}

cursor-server/src/cursor/handlers.rs

@@ -1,7 +1,7 @@
 use axum::{
     body::Bytes,
-    extract::{DefaultBodyLimit, State},
-    http::{header, HeaderValue, Response, StatusCode},
+    extract::{DefaultBodyLimit, Extension, State},
+    http::{header, HeaderMap, HeaderValue, Response, StatusCode},
     routing::post,
     Router,
 };
@@ -9,28 +9,45 @@ use tower_http::decompression::RequestDecompressionLayer;
 
 use crate::{
     cursor::{
-        bidi_append, connect,
+        bidi_append, connect, model_catalog,
         proto::{agent::v1 as agent, aiserver::v1 as ai},
+        proxy::{self, CursorProxy},
         run_sse,
     },
-    run::RunRegistry,
+    cursor::{CursorParent, CursorSessionRegistry},
     Result,
 };
 
-pub fn router(registry: RunRegistry) -> Router {
-    Router::new()
+pub fn router(registry: CursorSessionRegistry) -> Result<Router> {
+    let proxy = CursorProxy::cursor()?;
+    Ok(Router::new()
         .route("/agent.v1.AgentService/RunSSE", post(run_sse_handler))
         .route(
             "/aiserver.v1.BidiService/BidiAppend",
             post(bidi_append_handler),
         )
-        .layer(DefaultBodyLimit::disable())
-        .layer(RequestDecompressionLayer::new())
-        .with_state(registry)
+        .route(
+            "/aiserver.v1.AiService/AvailableModels",
+            post(model_catalog::available_models),
+        )
+        .route(
+            "/agent.v1.AgentService/GetUsableModels",
+            post(model_catalog::usable_models),
+        )
+        .route(
+            "/aiserver.v1.AiService/GetUsableModels",
+            post(model_catalog::usable_models),
+        )
+        .route_layer(DefaultBodyLimit::disable())
+        .route_layer(RequestDecompressionLayer::new())
+        .fallback(proxy::forward)
+        .method_not_allowed_fallback(proxy::forward)
+        .layer(Extension(proxy))
+        .with_state(registry))
 }
 
 async fn run_sse_handler(
-    State(registry): State<RunRegistry>,
+    State(registry): State<CursorSessionRegistry>,
     body: Bytes,
 ) -> Result<Response<axum::body::Body>> {
     let request: agent::BidiRequestId = connect::decode_unary(&body)?;
@@ -38,11 +55,13 @@ async fn run_sse_handler(
 }
 
 async fn bidi_append_handler(
-    State(registry): State<RunRegistry>,
+    State(registry): State<CursorSessionRegistry>,
+    headers: HeaderMap,
     body: Bytes,
 ) -> Result<Response<axum::body::Body>> {
     let request: ai::BidiAppendRequest = connect::decode_unary(&body)?;
-    bidi_append::append(&registry, request).await?;
+    let parent = parent_headers(&headers)?;
+    bidi_append::append(&registry, request, parent).await?;
     let mut response = Response::new(axum::body::Body::empty());
     *response.status_mut() = StatusCode::OK;
     response.headers_mut().insert(
@@ -51,3 +70,53 @@ async fn bidi_append_handler(
     );
     Ok(response)
 }
+
+fn parent_headers(headers: &HeaderMap) -> Result<Option<CursorParent>> {
+    let run_id = header_text(headers, "x-parent-request-id")?;
+    let tool_call_id = header_text(headers, "x-parent-agent-tool-call-id")?;
+    match (run_id, tool_call_id) {
+        (None, None) => Ok(None),
+        (Some(run_id), Some(tool_call_id)) => Ok(Some(CursorParent {
+            run_id: run_id.into(),
+            tool_call_id: tool_call_id.into(),
+        })),
+        _ => Err(crate::Error::Protocol(
+            "Cursor subagent request must include both parent headers".into(),
+        )),
+    }
+}
+
+fn header_text<'a>(headers: &'a HeaderMap, name: &str) -> Result<Option<&'a str>> {
+    headers
+        .get(name)
+        .map(|value| value.to_str())
+        .transpose()
+        .map_err(|error| crate::Error::Protocol(format!("invalid {name} header: {error}")))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn subagent_parent_headers_are_an_atomic_pair() {
+        let mut headers = HeaderMap::new();
+        headers.insert(
+            "x-parent-request-id",
+            HeaderValue::from_static("parent-run"),
+        );
+        assert!(parent_headers(&headers).is_err());
+
+        headers.insert(
+            "x-parent-agent-tool-call-id",
+            HeaderValue::from_static("parent-call"),
+        );
+        assert_eq!(
+            parent_headers(&headers).unwrap(),
+            Some(CursorParent {
+                run_id: "parent-run".into(),
+                tool_call_id: "parent-call".into(),
+            })
+        );
+    }
+}

cursor-server/src/cursor/inbox.rs

@@ -0,0 +1,38 @@
+use std::collections::BTreeMap;
+
+#[derive(Debug)]
+pub struct OrderedInbox<T> {
+    next: i64,
+    pending: BTreeMap<i64, T>,
+}
+
+impl<T> Default for OrderedInbox<T> {
+    fn default() -> Self {
+        Self {
+            next: 0,
+            pending: BTreeMap::new(),
+        }
+    }
+}
+
+impl<T> OrderedInbox<T> {
+    pub fn starting_at(next: i64) -> Self {
+        Self {
+            next,
+            pending: BTreeMap::new(),
+        }
+    }
+
+    pub fn push(&mut self, seqno: i64, value: T) -> Vec<(i64, T)> {
+        if seqno < self.next {
+            return Vec::new();
+        }
+        self.pending.entry(seqno).or_insert(value);
+        let mut ready = Vec::new();
+        while let Some(value) = self.pending.remove(&self.next) {
+            ready.push((self.next, value));
+            self.next += 1;
+        }
+        ready
+    }
+}

cursor-server/src/cursor/interaction/mod.rs

@@ -0,0 +1,105 @@
+mod query;
+mod render;
+
+use std::time::Duration;
+
+use crate::{
+    cursor::proto::agent::v1 as pb,
+    model::{ToolCall, Usage},
+    provider::ModelEvent,
+    Result,
+};
+
+pub use query::tool_query;
+pub(crate) use render::{edit_content_delta, edit_path_partial};
+pub use render::{render_tool_call, tool_completed, tool_placeholder, tool_started};
+
+pub fn response_event(
+    event: &ModelEvent,
+    model_call_id: &str,
+) -> Result<Option<pb::AgentServerMessage>> {
+    use pb::interaction_update::Message;
+    let message = match event {
+        ModelEvent::TextDelta(text) => Message::TextDelta(pb::TextDeltaUpdate {
+            text: text.clone(),
+            is_server_notice: false,
+        }),
+        ModelEvent::ThinkingDelta(text) => Message::ThinkingDelta(pb::ThinkingDeltaUpdate {
+            text: text.clone(),
+            thinking_style: Some(pb::ThinkingStyle::Default as i32),
+        }),
+        ModelEvent::ToolCallStart { call_id, name, .. } => {
+            Message::PartialToolCall(pb::PartialToolCallUpdate {
+                call_id: call_id.clone(),
+                tool_call: Some(tool_placeholder(name, call_id)?),
+                args_text_delta: String::new(),
+                model_call_id: model_call_id.into(),
+            })
+        }
+        ModelEvent::ToolCallArgumentsDelta { .. } => return Ok(None),
+        ModelEvent::ToolCallEnd { .. }
+        | ModelEvent::Start { .. }
+        | ModelEvent::TextStart
+        | ModelEvent::TextEnd
+        | ModelEvent::ThinkingStart
+        | ModelEvent::ThinkingEnd
+        | ModelEvent::ProviderReplayState(_)
+        | ModelEvent::Usage(_)
+        | ModelEvent::Done(_) => return Ok(None),
+    };
+    Ok(Some(server_interaction(message)))
+}
+
+pub fn thinking_completed(elapsed: Duration) -> pb::AgentServerMessage {
+    let milliseconds = elapsed.as_millis().clamp(1, i32::MAX as u128) as i32;
+    server_interaction(pb::interaction_update::Message::ThinkingCompleted(
+        pb::ThinkingCompletedUpdate {
+            thinking_duration_ms: milliseconds,
+        },
+    ))
+}
+
+pub fn arguments_delta(call: &ToolCall, delta: &str) -> Result<pb::AgentServerMessage> {
+    Ok(server_interaction(
+        pb::interaction_update::Message::PartialToolCall(pb::PartialToolCallUpdate {
+            call_id: call.call_id.clone(),
+            tool_call: Some(tool_placeholder(&call.name, &call.call_id)?),
+            args_text_delta: delta.into(),
+            model_call_id: call.model_call_id.clone(),
+        }),
+    ))
+}
+
+pub fn turn_ended(usage: Option<Usage>) -> pb::AgentServerMessage {
+    server_interaction(pb::interaction_update::Message::TurnEnded(
+        pb::TurnEndedUpdate {
+            input_tokens: usage.and_then(|usage| usage.input_tokens.map(|value| value as i64)),
+            output_tokens: usage.and_then(|usage| usage.output_tokens.map(|value| value as i64)),
+            cache_read_tokens: usage
+                .and_then(|usage| usage.cache_read_tokens.map(|value| value as i64)),
+            cache_write_tokens: usage
+                .and_then(|usage| usage.cache_write_tokens.map(|value| value as i64)),
+            reasoning_tokens: usage
+                .and_then(|usage| usage.reasoning_tokens.map(|value| value as i64)),
+        },
+    ))
+}
+
+pub fn token_delta(tokens: u64) -> pb::AgentServerMessage {
+    server_interaction(pb::interaction_update::Message::TokenDelta(
+        pb::TokenDeltaUpdate {
+            tokens: tokens.min(i32::MAX as u64) as i32,
+        },
+    ))
+}
+
+pub fn server_interaction(message: pb::interaction_update::Message) -> pb::AgentServerMessage {
+    pb::AgentServerMessage {
+        ttft_breakdown: None,
+        message: Some(pb::agent_server_message::Message::InteractionUpdate(
+            pb::InteractionUpdate {
+                message: Some(message),
+            },
+        )),
+    }
+}

cursor-server/src/cursor/interaction/query.rs

@@ -0,0 +1,205 @@
+use serde_json::Value;
+
+use crate::{cursor::proto::agent::v1 as pb, model::ToolCall, Error, Result};
+
+pub fn tool_query(id: u32, call: &ToolCall) -> Result<pb::AgentServerMessage> {
+    use pb::interaction_query::Query;
+    let string = |name: &str| {
+        call.arguments
+            .get(name)
+            .and_then(Value::as_str)
+            .map(str::to_string)
+            .ok_or_else(|| Error::Protocol(format!("{} is missing {name}", call.name)))
+    };
+    let optional_string = |name: &str| {
+        call.arguments
+            .get(name)
+            .and_then(Value::as_str)
+            .map(str::to_string)
+    };
+    let query = match normalized(&call.name).as_str() {
+        "askquestion" => {
+            let questions = call
+                .arguments
+                .get("questions")
+                .and_then(Value::as_array)
+                .into_iter()
+                .flatten()
+                .map(|question| -> Result<_> {
+                    let required = |name: &str| {
+                        question
+                            .get(name)
+                            .and_then(Value::as_str)
+                            .map(str::to_string)
+                            .ok_or_else(|| Error::Protocol(format!("question is missing {name}")))
+                    };
+                    let options = question
+                        .get("options")
+                        .and_then(Value::as_array)
+                        .into_iter()
+                        .flatten()
+                        .map(|option| -> Result<_> {
+                            let value = |name: &str| {
+                                option
+                                    .get(name)
+                                    .and_then(Value::as_str)
+                                    .map(str::to_string)
+                                    .ok_or_else(|| {
+                                        Error::Protocol(format!(
+                                            "question option is missing {name}"
+                                        ))
+                                    })
+                            };
+                            Ok(pb::ask_question_args::Option {
+                                id: value("id")?,
+                                label: value("label")?,
+                            })
+                        })
+                        .collect::<Result<Vec<_>>>()?;
+                    Ok(pb::ask_question_args::Question {
+                        id: required("id")?,
+                        prompt: required("prompt")?,
+                        options,
+                        allow_multiple: question
+                            .get("allow_multiple")
+                            .and_then(Value::as_bool)
+                            .unwrap_or(false),
+                    })
+                })
+                .collect::<Result<Vec<_>>>()?;
+            Query::AskQuestionInteractionQuery(pb::AskQuestionInteractionQuery {
+                args: Some(pb::AskQuestionArgs {
+                    title: optional_string("title").unwrap_or_default(),
+                    questions,
+                    run_async: false,
+                    async_original_tool_call_id: String::new(),
+                }),
+                tool_call_id: call.call_id.clone(),
+            })
+        }
+        "websearch" => Query::WebSearchRequestQuery(pb::WebSearchRequestQuery {
+            args: Some(pb::WebSearchArgs {
+                search_term: string("search_term")?,
+                tool_call_id: call.call_id.clone(),
+            }),
+        }),
+        "webfetch" => Query::WebFetchRequestQuery(pb::WebFetchRequestQuery {
+            args: Some(pb::WebFetchArgs {
+                url: string("url")?,
+                tool_call_id: call.call_id.clone(),
+            }),
+            skip_approval: false,
+            smart_mode_approval: smart_mode_approval(
+                call,
+                "requestSmartModeApproval",
+                "smartModeBlockReason",
+            )?,
+        }),
+        "switchmode" => Query::SwitchModeRequestQuery(pb::SwitchModeRequestQuery {
+            args: Some(pb::SwitchModeArgs {
+                target_mode_id: string("target_mode_id")?,
+                explanation: optional_string("explanation"),
+                tool_call_id: call.call_id.clone(),
+            }),
+        }),
+        "createplan" => {
+            let todos = call
+                .arguments
+                .get("todos")
+                .and_then(Value::as_array)
+                .into_iter()
+                .flatten()
+                .map(|todo| pb::TodoItem {
+                    id: todo
+                        .get("id")
+                        .and_then(Value::as_str)
+                        .unwrap_or_default()
+                        .into(),
+                    content: todo
+                        .get("content")
+                        .and_then(Value::as_str)
+                        .unwrap_or_default()
+                        .into(),
+                    status: pb::TodoStatus::Pending as i32,
+                    created_at: 0,
+                    updated_at: 0,
+                    dependencies: Vec::new(),
+                })
+                .collect();
+            Query::CreatePlanRequestQuery(pb::CreatePlanRequestQuery {
+                args: Some(pb::CreatePlanArgs {
+                    plan: string("plan")?,
+                    todos,
+                    overview: string("overview")?,
+                    name: string("name")?,
+                    is_project: false,
+                    phases: Vec::new(),
+                }),
+                tool_call_id: call.call_id.clone(),
+            })
+        }
+        "generateimage" => Query::GenerateImageRequestQuery(pb::GenerateImageRequestQuery {
+            args: Some(pb::GenerateImageArgs {
+                description: string("description")?,
+                file_path: optional_string("filename"),
+                reference_image_paths: call
+                    .arguments
+                    .get("reference_image_paths")
+                    .and_then(Value::as_array)
+                    .into_iter()
+                    .flatten()
+                    .filter_map(Value::as_str)
+                    .map(str::to_string)
+                    .collect(),
+                aspect_ratio: optional_string("aspect_ratio"),
+            }),
+            tool_call_id: call.call_id.clone(),
+        }),
+        other => {
+            return Err(Error::Protocol(format!(
+                "tool {other} is not an InteractionQuery"
+            )))
+        }
+    };
+    Ok(pb::AgentServerMessage {
+        ttft_breakdown: None,
+        message: Some(pb::agent_server_message::Message::InteractionQuery(
+            pb::InteractionQuery {
+                id,
+                query: Some(query),
+            },
+        )),
+    })
+}
+
+fn smart_mode_approval(
+    call: &ToolCall,
+    request_field: &str,
+    reason_field: &str,
+) -> Result<Option<pb::SmartModeApproval>> {
+    if !call
+        .arguments
+        .get(request_field)
+        .and_then(Value::as_bool)
+        .unwrap_or(false)
+    {
+        return Ok(None);
+    }
+    let reason = call
+        .arguments
+        .get(reason_field)
+        .and_then(Value::as_str)
+        .ok_or_else(|| Error::Protocol(format!("{} requires {reason_field}", call.name)))?;
+    Ok(Some(pb::SmartModeApproval {
+        request_id: call.call_id.clone(),
+        reason: reason.to_string(),
+    }))
+}
+
+fn normalized(value: &str) -> String {
+    value
+        .chars()
+        .filter(|character| character.is_ascii_alphanumeric())
+        .flat_map(char::to_lowercase)
+        .collect()
+}

cursor-server/src/cursor/interaction/render.rs

@@ -1,69 +1,56 @@
+use serde_json::Value;
+
 use crate::{
     cursor::{
         proto::agent::v1 as pb,
-        tool_result::{self, ToolCompletion},
+        tools::{
+            codec, edit,
+            result::{self as tool_result, ToolCompletion},
+        },
     },
-    model::{ToolCall, Usage},
-    provider::ResponseEvent,
+    model::ToolCall,
+    Error, Result,
 };
-use serde_json::Value;
-use std::time::Duration;
 
-use crate::{Error, Result};
+use super::server_interaction;
 
-pub fn response_event(
-    event: &ResponseEvent,
-    model_call_id: &str,
-) -> Result<Option<pb::AgentServerMessage>> {
-    use pb::interaction_update::Message;
-    let message = match event {
-        ResponseEvent::TextDelta(text) => Message::TextDelta(pb::TextDeltaUpdate {
-            text: text.clone(),
-            is_server_notice: false,
-        }),
-        ResponseEvent::ThinkingDelta(text) => Message::ThinkingDelta(pb::ThinkingDeltaUpdate {
-            text: text.clone(),
-            thinking_style: Some(pb::ThinkingStyle::Default as i32),
-        }),
-        ResponseEvent::ToolCallStart { call_id, name, .. } => {
-            Message::PartialToolCall(pb::PartialToolCallUpdate {
-                call_id: call_id.clone(),
-                tool_call: Some(tool_placeholder(name, call_id)?),
-                args_text_delta: String::new(),
-                model_call_id: model_call_id.into(),
-            })
-        }
-        ResponseEvent::ToolCallArgumentsDelta { .. } => return Ok(None),
-        ResponseEvent::ToolCallEnd { .. }
-        | ResponseEvent::Start { .. }
-        | ResponseEvent::TextStart
-        | ResponseEvent::TextEnd
-        | ResponseEvent::ThinkingStart
-        | ResponseEvent::ThinkingEnd
-        | ResponseEvent::Usage(_)
-        | ResponseEvent::Done(_) => return Ok(None),
-    };
-    Ok(Some(server_interaction(message)))
-}
-
-pub fn thinking_completed(elapsed: Duration) -> pb::AgentServerMessage {
-    let milliseconds = elapsed.as_millis().clamp(1, i32::MAX as u128) as i32;
-    server_interaction(pb::interaction_update::Message::ThinkingCompleted(
-        pb::ThinkingCompletedUpdate {
-            thinking_duration_ms: milliseconds,
+pub(crate) fn edit_path_partial(call: &ToolCall, path: &str) -> pb::AgentServerMessage {
+    server_interaction(pb::interaction_update::Message::PartialToolCall(
+        pb::PartialToolCallUpdate {
+            call_id: call.call_id.clone(),
+            tool_call: Some(pb::ToolCall {
+                hook_additional_contexts: Vec::new(),
+                tool_call_id: Some(call.call_id.clone()),
+                started_at_ms: None,
+                completed_at_ms: None,
+                tool: Some(pb::tool_call::Tool::EditToolCall(pb::EditToolCall {
+                    args: Some(pb::EditArgs {
+                        path: path.into(),
+                        stream_content: None,
+                    }),
+                    result: None,
+                })),
+            }),
+            args_text_delta: String::new(),
+            model_call_id: call.model_call_id.clone(),
         },
     ))
 }
 
-pub fn arguments_delta(call: &ToolCall, delta: &str) -> Result<pb::AgentServerMessage> {
-    Ok(server_interaction(
-        pb::interaction_update::Message::PartialToolCall(pb::PartialToolCallUpdate {
+pub(crate) fn edit_content_delta(call: &ToolCall, content: String) -> pb::AgentServerMessage {
+    server_interaction(pb::interaction_update::Message::ToolCallDelta(Box::new(
+        pb::ToolCallDeltaUpdate {
             call_id: call.call_id.clone(),
-            tool_call: Some(tool_placeholder(&call.name, &call.call_id)?),
-            args_text_delta: delta.into(),
+            tool_call_delta: Some(Box::new(pb::ToolCallDelta {
+                delta: Some(pb::tool_call_delta::Delta::EditToolCallDelta(
+                    pb::EditToolCallDelta {
+                        stream_content_delta: content,
+                    },
+                )),
+            })),
             model_call_id: call.model_call_id.clone(),
-        }),
-    ))
+        },
+    )))
 }
 
 pub fn tool_started(call: &ToolCall) -> Result<pb::AgentServerMessage> {
@@ -86,198 +73,16 @@ pub fn tool_completed(call: &ToolCall, completion: &ToolCompletion) -> pb::Agent
     ))
 }
 
-pub fn turn_ended(usage: Usage) -> pb::AgentServerMessage {
-    server_interaction(pb::interaction_update::Message::TurnEnded(
-        pb::TurnEndedUpdate {
-            input_tokens: Some(usage.input_tokens as i64),
-            output_tokens: Some(usage.output_tokens as i64),
-            cache_read_tokens: Some(usage.cache_read_tokens as i64),
-            cache_write_tokens: Some(usage.cache_write_tokens as i64),
-            reasoning_tokens: Some(usage.reasoning_tokens as i64),
-        },
-    ))
-}
-
-pub fn tool_query(id: u32, call: &ToolCall) -> Result<pb::AgentServerMessage> {
-    use pb::interaction_query::Query;
-    let string = |name: &str| {
-        call.arguments
-            .get(name)
-            .and_then(Value::as_str)
-            .map(str::to_string)
-            .ok_or_else(|| Error::Protocol(format!("{} is missing {name}", call.name)))
-    };
-    let optional_string = |name: &str| {
-        call.arguments
-            .get(name)
-            .and_then(Value::as_str)
-            .map(str::to_string)
-    };
-    let query = match normalized(&call.name).as_str() {
-        "askquestion" => {
-            let questions = call
-                .arguments
-                .get("questions")
-                .and_then(Value::as_array)
-                .into_iter()
-                .flatten()
-                .map(|question| -> Result<_> {
-                    let required = |name: &str| {
-                        question
-                            .get(name)
-                            .and_then(Value::as_str)
-                            .map(str::to_string)
-                            .ok_or_else(|| Error::Protocol(format!("question is missing {name}")))
-                    };
-                    let options = question
-                        .get("options")
-                        .and_then(Value::as_array)
-                        .into_iter()
-                        .flatten()
-                        .map(|option| -> Result<_> {
-                            let value = |name: &str| {
-                                option
-                                    .get(name)
-                                    .and_then(Value::as_str)
-                                    .map(str::to_string)
-                                    .ok_or_else(|| {
-                                        Error::Protocol(format!(
-                                            "question option is missing {name}"
-                                        ))
-                                    })
-                            };
-                            Ok(pb::ask_question_args::Option {
-                                id: value("id")?,
-                                label: value("label")?,
-                            })
-                        })
-                        .collect::<Result<Vec<_>>>()?;
-                    Ok(pb::ask_question_args::Question {
-                        id: required("id")?,
-                        prompt: required("prompt")?,
-                        options,
-                        allow_multiple: question
-                            .get("allow_multiple")
-                            .and_then(Value::as_bool)
-                            .unwrap_or(false),
-                    })
-                })
-                .collect::<Result<Vec<_>>>()?;
-            Query::AskQuestionInteractionQuery(pb::AskQuestionInteractionQuery {
-                args: Some(pb::AskQuestionArgs {
-                    title: optional_string("title").unwrap_or_default(),
-                    questions,
-                    run_async: false,
-                    async_original_tool_call_id: String::new(),
-                }),
-                tool_call_id: call.call_id.clone(),
-            })
-        }
-        "websearch" => Query::WebSearchRequestQuery(pb::WebSearchRequestQuery {
-            args: Some(pb::WebSearchArgs {
-                search_term: string("search_term")?,
-                tool_call_id: call.call_id.clone(),
-            }),
-        }),
-        "webfetch" => Query::WebFetchRequestQuery(pb::WebFetchRequestQuery {
-            args: Some(pb::WebFetchArgs {
-                url: string("url")?,
-                tool_call_id: call.call_id.clone(),
-            }),
-            skip_approval: false,
-            smart_mode_approval: None,
-        }),
-        "switchmode" => Query::SwitchModeRequestQuery(pb::SwitchModeRequestQuery {
-            args: Some(pb::SwitchModeArgs {
-                target_mode_id: string("target_mode_id")?,
-                explanation: optional_string("explanation"),
-                tool_call_id: call.call_id.clone(),
-            }),
-        }),
-        "createplan" => {
-            let todos = call
-                .arguments
-                .get("todos")
-                .and_then(Value::as_array)
-                .into_iter()
-                .flatten()
-                .map(|todo| pb::TodoItem {
-                    id: todo
-                        .get("id")
-                        .and_then(Value::as_str)
-                        .unwrap_or_default()
-                        .into(),
-                    content: todo
-                        .get("content")
-                        .and_then(Value::as_str)
-                        .unwrap_or_default()
-                        .into(),
-                    status: pb::TodoStatus::Pending as i32,
-                    created_at: 0,
-                    updated_at: 0,
-                    dependencies: Vec::new(),
-                })
-                .collect();
-            Query::CreatePlanRequestQuery(pb::CreatePlanRequestQuery {
-                args: Some(pb::CreatePlanArgs {
-                    plan: string("plan")?,
-                    todos,
-                    overview: string("overview")?,
-                    name: string("name")?,
-                    is_project: false,
-                    phases: Vec::new(),
-                }),
-                tool_call_id: call.call_id.clone(),
-            })
-        }
-        "generateimage" => Query::GenerateImageRequestQuery(pb::GenerateImageRequestQuery {
-            args: Some(pb::GenerateImageArgs {
-                description: optional_string("description").unwrap_or_default(),
-                file_path: optional_string("file_path"),
-                reference_image_paths: Vec::new(),
-                aspect_ratio: optional_string("aspect_ratio"),
-            }),
-            tool_call_id: call.call_id.clone(),
-        }),
-        other => {
-            return Err(Error::Protocol(format!(
-                "tool {other} is not an InteractionQuery"
-            )))
-        }
-    };
-    Ok(pb::AgentServerMessage {
-        ttft_breakdown: None,
-        message: Some(pb::agent_server_message::Message::InteractionQuery(
-            pb::InteractionQuery {
-                id,
-                query: Some(query),
-            },
-        )),
-    })
-}
-
-pub fn server_interaction(message: pb::interaction_update::Message) -> pb::AgentServerMessage {
-    pb::AgentServerMessage {
-        ttft_breakdown: None,
-        message: Some(pb::agent_server_message::Message::InteractionUpdate(
-            pb::InteractionUpdate {
-                message: Some(message),
-            },
-        )),
-    }
-}
-
 pub fn tool_placeholder(name: &str, call_id: &str) -> Result<pb::ToolCall> {
     use pb::tool_call::Tool;
     let tool = match normalized(name).as_str() {
-        "shell" | "forcebackgroundshell" => Tool::ShellToolCall(pb::ShellToolCall::default()),
+        "shell" => Tool::ShellToolCall(pb::ShellToolCall::default()),
         "delete" => Tool::DeleteToolCall(pb::DeleteToolCall::default()),
         "glob" => Tool::GlobToolCall(pb::GlobToolCall::default()),
         "grep" => Tool::GrepToolCall(pb::GrepToolCall::default()),
         "read" => Tool::ReadToolCall(pb::ReadToolCall::default()),
         "todowrite" => Tool::UpdateTodosToolCall(pb::UpdateTodosToolCall::default()),
-        "patchedit" | "write" => Tool::EditToolCall(pb::EditToolCall::default()),
-        "ls" => Tool::LsToolCall(pb::LsToolCall::default()),
+        "strreplace" | "editnotebook" | "write" => Tool::EditToolCall(pb::EditToolCall::default()),
         "readlints" => Tool::ReadLintsToolCall(pb::ReadLintsToolCall::default()),
         "callmcptool" => Tool::McpToolCall(pb::McpToolCall::default()),
         "createplan" => Tool::CreatePlanToolCall(pb::CreatePlanToolCall::default()),
@@ -288,10 +93,11 @@ pub fn tool_placeholder(name: &str, call_id: &str) -> Result<pb::ToolCall> {
         "webfetch" => Tool::WebFetchToolCall(pb::WebFetchToolCall::default()),
         "switchmode" => Tool::SwitchModeToolCall(pb::SwitchModeToolCall::default()),
         "generateimage" => Tool::GenerateImageToolCall(pb::GenerateImageToolCall::default()),
-        "communicateupdate" => {
+        "updatecurrentstep" => {
             Tool::CommunicateUpdateToolCall(pb::CommunicateUpdateToolCall::default())
         }
-        "writeshellstdin" => Tool::WriteShellStdinToolCall(pb::WriteShellStdinToolCall::default()),
+        "awaitshell" => Tool::AwaitToolCall(pb::AwaitToolCall::default()),
+        "getmcptools" => Tool::GetMcpToolsToolCall(pb::GetMcpToolsToolCall::default()),
         _ => return Err(Error::Protocol(format!("unsupported tool: {name}"))),
     };
     Ok(pb::ToolCall {
@@ -387,18 +193,15 @@ pub fn render_tool_call(call: &ToolCall, completed: bool) -> Result<pb::ToolCall
             let stream_content = if normalized(&call.name) == "write" {
                 optional("contents").unwrap_or_default()
             } else {
-                format!("{}\n---\n{}", string("old_string"), string("new_string"))
+                optional("new_string").unwrap_or_default()
             };
             tool.args = Some(pb::EditArgs {
-                path: string("path"),
-                stream_content: Some(stream_content),
-            })
-        }
-        Some(pb::tool_call::Tool::LsToolCall(tool)) => {
-            tool.args = Some(pb::LsArgs {
-                path: string("path"),
-                tool_call_id: call.call_id.clone(),
-                ..Default::default()
+                path: if normalized(&call.name) == "editnotebook" {
+                    string("target_notebook")
+                } else {
+                    string("path")
+                },
+                stream_content: Some(edit::normalize_newlines(&stream_content)),
             })
         }
         Some(pb::tool_call::Tool::ReadLintsToolCall(tool)) => {
@@ -421,7 +224,7 @@ pub fn render_tool_call(call: &ToolCall, completed: bool) -> Result<pb::ToolCall
                     .arguments
                     .get("arguments")
                     .and_then(Value::as_object)
-                    .map(super::exec::json_object_to_prost)
+                    .map(codec::json_object_to_prost)
                     .unwrap_or_default(),
                 tool_call_id: call.call_id.clone(),
                 tool_name: optional("toolName").unwrap_or_default(),
@@ -453,10 +256,18 @@ pub fn render_tool_call(call: &ToolCall, completed: bool) -> Result<pb::ToolCall
                 model: optional("model"),
                 resume: optional("resume"),
                 agent_id: None,
-                attachments: Vec::new(),
+                attachments: call
+                    .arguments
+                    .get("file_attachments")
+                    .and_then(Value::as_array)
+                    .into_iter()
+                    .flatten()
+                    .filter_map(Value::as_str)
+                    .map(str::to_string)
+                    .collect(),
                 mode: 0,
                 responding_to_message_ids: Vec::new(),
-                environment: 0,
+                environment: execution_environment(optional("environment").as_deref()),
                 machine: None,
             })
         }
@@ -485,8 +296,16 @@ pub fn render_tool_call(call: &ToolCall, completed: bool) -> Result<pb::ToolCall
         Some(pb::tool_call::Tool::GenerateImageToolCall(tool)) => {
             tool.args = Some(pb::GenerateImageArgs {
                 description: string("description"),
-                file_path: optional("file_path"),
-                reference_image_paths: Vec::new(),
+                file_path: optional("filename"),
+                reference_image_paths: call
+                    .arguments
+                    .get("reference_image_paths")
+                    .and_then(Value::as_array)
+                    .into_iter()
+                    .flatten()
+                    .filter_map(Value::as_str)
+                    .map(str::to_string)
+                    .collect(),
                 aspect_ratio: optional("aspect_ratio"),
             })
         }
@@ -507,6 +326,25 @@ pub fn render_tool_call(call: &ToolCall, completed: bool) -> Result<pb::ToolCall
                 chars: string("chars"),
             })
         }
+        Some(pb::tool_call::Tool::AwaitToolCall(tool)) => {
+            tool.args = Some(pb::AwaitArgs {
+                task_id: string("shell_id"),
+                block_until_ms: call
+                    .arguments
+                    .get("block_until_ms")
+                    .and_then(Value::as_u64)
+                    .map(|v| v as u32),
+                regex: optional("pattern"),
+            })
+        }
+        Some(pb::tool_call::Tool::GetMcpToolsToolCall(tool)) => {
+            tool.args = Some(pb::GetMcpToolsArgs {
+                server: optional("server"),
+                tool_name: optional("toolName"),
+                pattern: optional("pattern"),
+                tool_call_id: call.call_id.clone(),
+            })
+        }
         _ => {}
     }
     Ok(output)
@@ -515,22 +353,29 @@ pub fn render_tool_call(call: &ToolCall, completed: bool) -> Result<pb::ToolCall
 fn subagent_type(name: &str) -> pb::SubagentType {
     use pb::subagent_type::Type;
     let r#type = match name.to_ascii_lowercase().as_str() {
+        "" | "generalpurpose" => Type::Unspecified(pb::SubagentTypeUnspecified {}),
         "explore" => Type::Explore(pb::SubagentTypeExplore {}),
         "browser-use" | "browseruse" => Type::BrowserUse(pb::SubagentTypeBrowserUse {}),
         "shell" => Type::Shell(pb::SubagentTypeShell {}),
         "bash" => Type::Bash(pb::SubagentTypeBash {}),
         "debug" => Type::Debug(pb::SubagentTypeDebug {}),
+        "cursor-guide" | "cursorguide" => Type::CursorGuide(pb::SubagentTypeCursorGuide {}),
         "computer-use" | "computeruse" => Type::ComputerUse(pb::SubagentTypeComputerUse {}),
-        "" => Type::Unspecified(pb::SubagentTypeUnspecified {}),
-        custom => Type::Custom(pb::SubagentTypeCustom {
-            name: custom.into(),
-        }),
+        _ => Type::Custom(pb::SubagentTypeCustom { name: name.into() }),
     };
     pb::SubagentType {
         r#type: Some(r#type),
     }
 }
 
+fn execution_environment(value: Option<&str>) -> i32 {
+    match value {
+        Some("cloud") => pb::SubagentExecutionEnvironment::Cloud as i32,
+        Some("local") | None => pb::SubagentExecutionEnvironment::Local as i32,
+        Some(_) => pb::SubagentExecutionEnvironment::Unspecified as i32,
+    }
+}
+
 fn normalized(value: &str) -> String {
     value
         .chars()

cursor-server/src/cursor/json_stream.rs

@@ -0,0 +1,269 @@
+use crate::{Error, Result};
+
+#[derive(Debug, PartialEq)]
+pub(crate) enum StringFieldEvent {
+    Delta { name: String, text: String },
+    End { name: String },
+}
+
+#[derive(Default)]
+pub(crate) struct JsonStringFields {
+    state: State,
+    key: String,
+    string: JsonString,
+    skipped: SkippedValue,
+}
+
+#[derive(Default)]
+enum State {
+    #[default]
+    Object,
+    Key,
+    KeyString,
+    Colon,
+    Value,
+    ValueString,
+    SkipValue,
+    AfterValue,
+    Done,
+}
+
+impl JsonStringFields {
+    pub fn push(&mut self, input: &str) -> Result<Vec<StringFieldEvent>> {
+        let mut events = Vec::new();
+        for character in input.chars() {
+            self.consume(character, &mut events)?;
+        }
+        Ok(events)
+    }
+
+    fn consume(&mut self, character: char, events: &mut Vec<StringFieldEvent>) -> Result<()> {
+        match self.state {
+            State::Object => match character {
+                '{' => self.state = State::Key,
+                value if value.is_whitespace() => {}
+                _ => return Err(protocol("tool arguments must start with an object")),
+            },
+            State::Key => match character {
+                '"' => {
+                    self.key.clear();
+                    self.string.clear();
+                    self.state = State::KeyString;
+                }
+                '}' => self.state = State::Done,
+                value if value.is_whitespace() => {}
+                _ => return Err(protocol("expected a tool argument name")),
+            },
+            State::KeyString => match self.string.push(character)? {
+                StringStep::Text(text) => self.key.push_str(&text),
+                StringStep::End => self.state = State::Colon,
+                StringStep::Pending => {}
+            },
+            State::Colon => match character {
+                ':' => self.state = State::Value,
+                value if value.is_whitespace() => {}
+                _ => return Err(protocol("expected ':' after tool argument name")),
+            },
+            State::Value => match character {
+                '"' => {
+                    self.string.clear();
+                    self.state = State::ValueString;
+                }
+                value if value.is_whitespace() => {}
+                value => {
+                    self.skipped.start(value);
+                    self.state = State::SkipValue;
+                }
+            },
+            State::ValueString => match self.string.push(character)? {
+                StringStep::Text(text) => push_delta(events, &self.key, text),
+                StringStep::End => {
+                    events.push(StringFieldEvent::End {
+                        name: self.key.clone(),
+                    });
+                    self.state = State::AfterValue;
+                }
+                StringStep::Pending => {}
+            },
+            State::SkipValue => {
+                if let Some(terminal) = self.skipped.push(character) {
+                    self.state = match terminal {
+                        ',' => State::Key,
+                        '}' => State::Done,
+                        _ => return Err(protocol("invalid skipped JSON value terminator")),
+                    };
+                }
+            }
+            State::AfterValue => match character {
+                ',' => self.state = State::Key,
+                '}' => self.state = State::Done,
+                value if value.is_whitespace() => {}
+                _ => return Err(protocol("expected ',' after tool argument value")),
+            },
+            State::Done if character.is_whitespace() => {}
+            State::Done => return Err(protocol("data after tool arguments object")),
+        }
+        Ok(())
+    }
+}
+
+fn push_delta(events: &mut Vec<StringFieldEvent>, name: &str, text: String) {
+    if let Some(StringFieldEvent::Delta {
+        name: previous_name,
+        text: previous_text,
+    }) = events.last_mut()
+    {
+        if previous_name == name {
+            previous_text.push_str(&text);
+            return;
+        }
+    }
+    events.push(StringFieldEvent::Delta {
+        name: name.into(),
+        text,
+    });
+}
+
+#[derive(Default)]
+struct JsonString {
+    escape: String,
+}
+
+enum StringStep {
+    Text(String),
+    End,
+    Pending,
+}
+
+impl JsonString {
+    fn clear(&mut self) {
+        self.escape.clear();
+    }
+
+    fn push(&mut self, character: char) -> Result<StringStep> {
+        if self.escape.is_empty() {
+            return match character {
+                '"' => Ok(StringStep::End),
+                '\\' => {
+                    self.escape.push(character);
+                    Ok(StringStep::Pending)
+                }
+                value if value < '\u{20}' => Err(protocol("control character in JSON string")),
+                value => Ok(StringStep::Text(value.to_string())),
+            };
+        }
+
+        self.escape.push(character);
+        let complete = match self.escape.as_bytes() {
+            [b'\\', b'u', a, b, c, d]
+                if [a, b, c, d].iter().all(|value| value.is_ascii_hexdigit()) =>
+            {
+                let code = u16::from_str_radix(&self.escape[2..], 16)
+                    .map_err(|_| protocol("invalid JSON unicode escape"))?;
+                !(0xD800..=0xDBFF).contains(&code)
+            }
+            [b'\\', b'u', ..] if self.escape.len() < 6 => false,
+            [b'\\', b'u', a, b, c, d, b'\\', b'u', e, f, g, h]
+                if [a, b, c, d, e, f, g, h]
+                    .iter()
+                    .all(|value| value.is_ascii_hexdigit()) =>
+            {
+                true
+            }
+            [b'\\', b'u', ..] if self.escape.len() < 12 => false,
+            [b'\\', b'"' | b'\\' | b'/' | b'b' | b'f' | b'n' | b'r' | b't'] => true,
+            [b'\\'] => false,
+            _ => return Err(protocol("invalid JSON string escape")),
+        };
+        if !complete {
+            return Ok(StringStep::Pending);
+        }
+        let quoted = format!("\"{}\"", self.escape);
+        let decoded: String = serde_json::from_str(&quoted)
+            .map_err(|error| protocol(&format!("invalid JSON string escape: {error}")))?;
+        self.escape.clear();
+        Ok(StringStep::Text(decoded))
+    }
+}
+
+#[derive(Default)]
+struct SkippedValue {
+    depth: usize,
+    string: bool,
+    escaped: bool,
+}
+
+impl SkippedValue {
+    fn start(&mut self, first: char) {
+        *self = Self::default();
+        self.observe(first);
+    }
+
+    fn push(&mut self, character: char) -> Option<char> {
+        if !self.string && self.depth == 0 && matches!(character, ',' | '}') {
+            return Some(character);
+        }
+        self.observe(character);
+        None
+    }
+
+    fn observe(&mut self, character: char) {
+        if self.string {
+            if self.escaped {
+                self.escaped = false;
+            } else if character == '\\' {
+                self.escaped = true;
+            } else if character == '"' {
+                self.string = false;
+            }
+            return;
+        }
+        match character {
+            '"' => self.string = true,
+            '{' | '[' => self.depth += 1,
+            '}' | ']' => self.depth = self.depth.saturating_sub(1),
+            _ => {}
+        }
+    }
+}
+
+fn protocol(message: &str) -> Error {
+    Error::Protocol(message.into())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn streams_top_level_strings_and_decodes_split_escapes() {
+        let mut fields = JsonStringFields::default();
+        let mut events = fields
+            .push("{\"path\":\"/tmp/a\",\"count\":1,\"contents\":\"a\\n\\uD8")
+            .unwrap();
+        events.extend(fields.push("3D\\uDE00b\"}").unwrap());
+        assert_eq!(
+            events,
+            vec![
+                StringFieldEvent::Delta {
+                    name: "path".into(),
+                    text: "/tmp/a".into()
+                },
+                StringFieldEvent::End {
+                    name: "path".into()
+                },
+                StringFieldEvent::Delta {
+                    name: "contents".into(),
+                    text: "a\n".into()
+                },
+                StringFieldEvent::Delta {
+                    name: "contents".into(),
+                    text: "😀b".into()
+                },
+                StringFieldEvent::End {
+                    name: "contents".into()
+                },
+            ]
+        );
+    }
+}

cursor-server/src/cursor/lifecycle.rs

@@ -0,0 +1,81 @@
+use base64::{engine::general_purpose::STANDARD_NO_PAD, Engine};
+use prost::Message;
+
+use crate::{
+    cursor::CursorSessionHandle,
+    cursor::{
+        connect::{
+            encode_end_stream, encode_error_end_stream, ConnectCode, ConnectErrorDetail,
+            ConnectStreamError,
+        },
+        proto::aiserver::v1 as ai,
+    },
+    Error, Result,
+};
+
+pub fn finish_success(handle: &CursorSessionHandle) {
+    handle.emit_frame(encode_end_stream());
+    handle.close_output();
+}
+
+pub fn fail(handle: &CursorSessionHandle, error: &Error) -> Result<()> {
+    let stream_error = match error {
+        Error::Provider(_) | Error::Http(_) => provider_error(error),
+        Error::Protocol(_) | Error::Decode(_) | Error::Json(_) => {
+            plain_error(ConnectCode::InvalidArgument, error)
+        }
+        Error::RunNotFound(_) => plain_error(ConnectCode::NotFound, error),
+        Error::Cancelled => plain_error(ConnectCode::Canceled, error),
+        Error::Config(_)
+        | Error::Store(_)
+        | Error::Database(_)
+        | Error::Migration(_)
+        | Error::Encode(_)
+        | Error::Io(_) => plain_error(ConnectCode::Internal, error),
+    };
+    handle.emit_frame(encode_error_end_stream(&stream_error)?);
+    handle.close_output();
+    Ok(())
+}
+
+pub fn cancel(handle: &CursorSessionHandle) -> Result<()> {
+    handle.emit_frame(encode_error_end_stream(&ConnectStreamError {
+        code: ConnectCode::Canceled,
+        message: "run was cancelled".into(),
+        details: Vec::new(),
+    })?);
+    handle.close_output();
+    Ok(())
+}
+
+fn plain_error(code: ConnectCode, error: &Error) -> ConnectStreamError {
+    ConnectStreamError {
+        code,
+        message: error.to_string(),
+        details: Vec::new(),
+    }
+}
+
+fn provider_error(error: &Error) -> ConnectStreamError {
+    let detail = ai::ErrorDetails {
+        error: ai::error_details::Error::ProviderError as i32,
+        details: Some(ai::CustomErrorDetails {
+            title: "Server Error".into(),
+            detail: error.to_string(),
+            allow_command_links_potentially_unsafe_please_only_use_for_handwritten_trusted_markdown:
+                Some(true),
+            is_retryable: Some(true),
+            show_request_id: Some(true),
+            should_show_immediate_error: Some(false),
+        }),
+        is_expected: Some(false),
+    };
+    ConnectStreamError {
+        code: ConnectCode::Unavailable,
+        message: error.to_string(),
+        details: vec![ConnectErrorDetail {
+            type_name: "aiserver.v1.ErrorDetails".into(),
+            value: STANDARD_NO_PAD.encode(detail.encode_to_vec()),
+        }],
+    }
+}

cursor-server/src/cursor/mod.rs

@@ -1,12 +1,26 @@
+mod actor;
 pub mod bidi_append;
 pub mod blob_sync;
 pub mod checkpoint;
 pub mod connect;
-pub mod exec;
 pub mod handlers;
+mod inbox;
 pub mod interaction;
-pub mod pending;
+mod json_stream;
+pub(crate) mod lifecycle;
+mod model_catalog;
+mod presentation;
+mod projection;
+pub mod prompting;
 pub mod proto;
+pub mod proxy;
+pub mod request;
 pub mod run_sse;
-pub mod tool_result;
+pub mod session;
+pub mod sessions;
 pub mod tools;
+mod usage;
+
+pub use command::CursorCommand;
+pub use sessions::{CursorParent, CursorSessionHandle, CursorSessionRegistry};
+mod command;

cursor-server/src/cursor/model_catalog.rs

@@ -0,0 +1,202 @@
+use axum::{
+    body::{Body, Bytes},
+    extract::{Extension, State},
+    http::{Request, Response},
+};
+use bytes::{BufMut, BytesMut};
+use prost::Message;
+
+use crate::{
+    cursor::{
+        proto::agent::v1 as agent,
+        proxy::{self, CursorProxy},
+        CursorSessionRegistry,
+    },
+    model::ProviderModel,
+    Error, Result,
+};
+
+#[derive(Clone, PartialEq, Message)]
+struct AvailableModelsAddition {
+    #[prost(string, repeated, tag = "1")]
+    model_names: Vec<String>,
+    #[prost(message, repeated, tag = "2")]
+    models: Vec<AvailableModel>,
+}
+
+#[derive(Clone, PartialEq, Message)]
+struct AvailableModel {
+    #[prost(string, tag = "1")]
+    name: String,
+    #[prost(bool, optional, tag = "5")]
+    supports_agent: Option<bool>,
+    #[prost(bool, optional, tag = "9")]
+    supports_thinking: Option<bool>,
+    #[prost(int32, optional, tag = "15")]
+    context_token_limit: Option<i32>,
+    #[prost(string, optional, tag = "17")]
+    client_display_name: Option<String>,
+    #[prost(string, optional, tag = "18")]
+    server_model_name: Option<String>,
+    #[prost(bool, optional, tag = "23")]
+    is_user_added: Option<bool>,
+    #[prost(string, optional, tag = "24")]
+    inputbox_short_model_name: Option<String>,
+}
+
+#[derive(Clone, PartialEq, Message)]
+struct UsableModelsAddition {
+    #[prost(message, repeated, tag = "1")]
+    models: Vec<agent::ModelDetails>,
+}
+
+pub async fn available_models(
+    State(registry): State<CursorSessionRegistry>,
+    Extension(proxy): Extension<CursorProxy>,
+    request: Request<Body>,
+) -> Result<Response<Body>> {
+    let models = registry.store().provider_models(true).await?;
+    merge_response(
+        proxy::forward_buffered(&proxy, request).await?,
+        AvailableModelsAddition {
+            model_names: models
+                .iter()
+                .map(|model| model.model_hash.clone())
+                .collect(),
+            models: models.iter().map(available_model).collect(),
+        }
+        .encode_to_vec(),
+    )
+}
+
+pub async fn usable_models(
+    State(registry): State<CursorSessionRegistry>,
+    Extension(proxy): Extension<CursorProxy>,
+    request: Request<Body>,
+) -> Result<Response<Body>> {
+    let models = registry.store().provider_models(true).await?;
+    merge_response(
+        proxy::forward_buffered(&proxy, request).await?,
+        UsableModelsAddition {
+            models: models.iter().map(usable_model).collect(),
+        }
+        .encode_to_vec(),
+    )
+}
+
+fn merge_response(upstream: proxy::BufferedResponse, extra: Vec<u8>) -> Result<Response<Body>> {
+    if !upstream.status.is_success() {
+        return Ok(upstream.into_response());
+    }
+    let (framed, payload) = unary_payload(&upstream.body)?;
+    let body = if framed {
+        let mut merged = BytesMut::with_capacity(5 + payload.len() + extra.len());
+        merged.put_u8(0);
+        merged.put_u32((payload.len() + extra.len()) as u32);
+        merged.extend_from_slice(payload);
+        merged.extend_from_slice(&extra);
+        merged.freeze()
+    } else {
+        let mut merged = BytesMut::with_capacity(payload.len() + extra.len());
+        merged.extend_from_slice(payload);
+        merged.extend_from_slice(&extra);
+        merged.freeze()
+    };
+    Ok(upstream.with_body(body))
+}
+
+fn unary_payload(body: &Bytes) -> Result<(bool, &[u8])> {
+    if body.len() < 5 {
+        return Ok((false, body));
+    }
+    let flags = body[0];
+    let length = u32::from_be_bytes([body[1], body[2], body[3], body[4]]) as usize;
+    if length != body.len() - 5 {
+        return Ok((false, body));
+    }
+    if flags != 0 {
+        return Err(Error::Protocol(format!(
+            "cannot merge compressed or terminal model catalog frame: flags={flags}"
+        )));
+    }
+    Ok((true, &body[5..]))
+}
+
+fn available_model(model: &ProviderModel) -> AvailableModel {
+    AvailableModel {
+        name: model.model_hash.clone(),
+        supports_agent: Some(true),
+        supports_thinking: Some(model.reasoning_enabled),
+        context_token_limit: model
+            .context_window_tokens
+            .map(|value| value.min(i32::MAX as u64) as i32),
+        client_display_name: Some(model.display_name.clone()),
+        server_model_name: Some(model.model_hash.clone()),
+        is_user_added: Some(true),
+        inputbox_short_model_name: Some(model.display_name.clone()),
+    }
+}
+
+fn usable_model(model: &ProviderModel) -> agent::ModelDetails {
+    agent::ModelDetails {
+        model_id: model.model_hash.clone(),
+        display_model_id: model.model_hash.clone(),
+        display_name: model.display_name.clone(),
+        display_name_short: model.display_name.clone(),
+        thinking_details: model
+            .reasoning_enabled
+            .then_some(agent::ThinkingDetails::default()),
+        ..Default::default()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use axum::body::{to_bytes, Bytes};
+
+    use super::*;
+
+    #[tokio::test]
+    async fn appends_models_without_reencoding_official_fields() {
+        // Unknown field 99 = 7 stands in for every official field this service does not know.
+        let official = Bytes::from_static(&[0x98, 0x06, 0x07]);
+        let addition = AvailableModelsAddition {
+            model_names: vec!["f246010a".into()],
+            models: Vec::new(),
+        }
+        .encode_to_vec();
+        let response = merge_response(
+            proxy::BufferedResponse {
+                status: axum::http::StatusCode::OK,
+                headers: Default::default(),
+                body: official.clone(),
+            },
+            addition.clone(),
+        )
+        .unwrap();
+        let merged = to_bytes(response.into_body(), usize::MAX).await.unwrap();
+        assert_eq!(&merged[..official.len()], official.as_ref());
+        assert_eq!(&merged[official.len()..], addition);
+    }
+
+    #[tokio::test]
+    async fn updates_connect_length_when_catalog_is_framed() {
+        let official = [0x98, 0x06, 0x07];
+        let mut framed = BytesMut::new();
+        framed.put_u8(0);
+        framed.put_u32(official.len() as u32);
+        framed.extend_from_slice(&official);
+        let response = merge_response(
+            proxy::BufferedResponse {
+                status: axum::http::StatusCode::OK,
+                headers: Default::default(),
+                body: framed.freeze(),
+            },
+            vec![0x0a, 0x01, b'x'],
+        )
+        .unwrap();
+        let merged = to_bytes(response.into_body(), usize::MAX).await.unwrap();
+        assert_eq!(u32::from_be_bytes(merged[1..5].try_into().unwrap()), 6);
+        assert_eq!(&merged[5..8], &official);
+    }
+}

cursor-server/src/cursor/pending.rs

@@ -1,139 +0,0 @@
-use std::{
-    collections::HashMap,
-    sync::{
-        atomic::{AtomicU32, Ordering},
-        Arc,
-    },
-};
-
-use tokio::sync::Mutex;
-
-use crate::{model::ToolCall, Error, Result};
-
-#[derive(Clone, Default)]
-pub struct PendingExecRegistry {
-    next_id: Arc<AtomicU32>,
-    entries: Arc<Mutex<HashMap<u32, PendingExec>>>,
-}
-
-pub(crate) struct PendingExec {
-    pub call: ToolCall,
-    pub context: ExecContext,
-    pub started_at_ms: u64,
-    pub stdout: String,
-    pub stderr: String,
-}
-
-#[derive(Clone, Debug, Default)]
-pub struct ExecContext {
-    pub conversation_id: String,
-    pub terminals_folder: String,
-    pub admin_command_denylist: Vec<String>,
-}
-
-#[derive(Clone, Default)]
-pub struct PendingClientTools {
-    next_id: Arc<AtomicU32>,
-    calls: Arc<Mutex<HashMap<u32, PendingClientTool>>>,
-}
-
-pub(crate) struct PendingClientTool {
-    pub call: ToolCall,
-    pub context: ExecContext,
-    pub started_at_ms: u64,
-}
-
-impl PendingExecRegistry {
-    pub async fn reserve(&self, call: &ToolCall, context: &ExecContext) -> Result<u32> {
-        let id = next_id(&self.next_id)?;
-        self.entries.lock().await.insert(
-            id,
-            PendingExec {
-                call: call.clone(),
-                context: context.clone(),
-                started_at_ms: now_ms(),
-                stdout: String::new(),
-                stderr: String::new(),
-            },
-        );
-        Ok(id)
-    }
-
-    pub async fn call(&self, id: u32) -> Option<ToolCall> {
-        self.entries
-            .lock()
-            .await
-            .get(&id)
-            .map(|entry| entry.call.clone())
-    }
-
-    pub async fn append_stdout(&self, id: u32, data: &str) -> bool {
-        let mut entries = self.entries.lock().await;
-        let Some(entry) = entries.get_mut(&id) else {
-            return false;
-        };
-        entry.stdout.push_str(data);
-        true
-    }
-
-    pub async fn append_stderr(&self, id: u32, data: &str) -> bool {
-        let mut entries = self.entries.lock().await;
-        let Some(entry) = entries.get_mut(&id) else {
-            return false;
-        };
-        entry.stderr.push_str(data);
-        true
-    }
-
-    pub(crate) async fn take(&self, id: u32) -> Option<PendingExec> {
-        self.entries.lock().await.remove(&id)
-    }
-
-    pub async fn discard(&self, id: u32) {
-        self.entries.lock().await.remove(&id);
-    }
-
-    pub async fn drain_running(&self) -> Vec<u32> {
-        let mut entries = self.entries.lock().await;
-        let mut ids = entries.drain().map(|(id, _)| id).collect::<Vec<_>>();
-        ids.sort_unstable();
-        ids
-    }
-}
-
-impl PendingClientTools {
-    pub async fn reserve(&self, call: &ToolCall, context: &ExecContext) -> Result<u32> {
-        let id = next_id(&self.next_id)?;
-        self.calls.lock().await.insert(
-            id,
-            PendingClientTool {
-                call: call.clone(),
-                context: context.clone(),
-                started_at_ms: now_ms(),
-            },
-        );
-        Ok(id)
-    }
-
-    pub(crate) async fn take(&self, id: u32) -> Option<PendingClientTool> {
-        self.calls.lock().await.remove(&id)
-    }
-
-    pub async fn discard(&self, id: u32) {
-        self.calls.lock().await.remove(&id);
-    }
-}
-
-fn next_id(counter: &AtomicU32) -> Result<u32> {
-    counter
-        .fetch_add(1, Ordering::Relaxed)
-        .checked_add(1)
-        .ok_or_else(|| Error::Protocol("Cursor message id space exhausted".into()))
-}
-
-pub(crate) fn now_ms() -> u64 {
-    std::time::SystemTime::now()
-        .duration_since(std::time::UNIX_EPOCH)
-        .unwrap_or_default()
-        .as_millis() as u64
-}

cursor-server/src/cursor/presentation.rs

@@ -0,0 +1,101 @@
+use std::time::Duration;
+
+use crate::cursor::{proto::agent::v1 as pb, tools::result::ToolCompletion};
+
+#[derive(Default)]
+pub struct PresentationDelta {
+    pub steps: Vec<pb::ConversationStep>,
+    pub read_paths: Vec<String>,
+}
+
+#[derive(Default)]
+pub struct Presentation {
+    steps: Vec<pb::ConversationStep>,
+    read_paths: Vec<String>,
+    text: String,
+    thinking: String,
+}
+
+impl Presentation {
+    pub fn text_delta(&mut self, delta: &str) {
+        self.text.push_str(delta);
+    }
+
+    pub fn finish_text(&mut self) {
+        if self.text.is_empty() {
+            return;
+        }
+        self.steps.push(pb::ConversationStep {
+            message: Some(pb::conversation_step::Message::AssistantMessage(
+                pb::AssistantMessage {
+                    text: std::mem::take(&mut self.text),
+                },
+            )),
+        });
+    }
+
+    pub fn thinking_delta(&mut self, delta: &str) {
+        self.thinking.push_str(delta);
+    }
+
+    pub fn finish_thinking(&mut self, duration: Duration) {
+        if self.thinking.is_empty() {
+            return;
+        }
+        self.steps.push(pb::ConversationStep {
+            message: Some(pb::conversation_step::Message::ThinkingMessage(
+                pb::ThinkingMessage {
+                    text: std::mem::take(&mut self.thinking),
+                    duration_ms: duration.as_millis().min(u32::MAX as u128) as u32,
+                },
+            )),
+        });
+    }
+
+    pub fn tool_completed(&mut self, completion: &ToolCompletion) {
+        if let Some(pb::tool_call::Tool::ReadToolCall(read)) = &completion.tool_call().tool {
+            if matches!(
+                read.result
+                    .as_ref()
+                    .and_then(|result| result.result.as_ref()),
+                Some(pb::read_tool_result::Result::Success(_))
+            ) {
+                if let Some(path) = read.args.as_ref().map(|args| &args.path) {
+                    if !path.is_empty() && !self.read_paths.contains(path) {
+                        self.read_paths.push(path.clone());
+                    }
+                }
+            }
+        }
+        self.steps.push(pb::ConversationStep {
+            message: Some(pb::conversation_step::Message::ToolCall(
+                completion.tool_call().clone(),
+            )),
+        });
+    }
+
+    pub fn take(&mut self) -> PresentationDelta {
+        PresentationDelta {
+            steps: std::mem::take(&mut self.steps),
+            read_paths: std::mem::take(&mut self.read_paths),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn thinking_step_keeps_the_measured_duration() {
+        let mut presentation = Presentation::default();
+        presentation.thinking_delta("reasoning");
+        presentation.finish_thinking(Duration::from_millis(6_880));
+        let step = presentation.take().steps.pop().unwrap();
+        let Some(pb::conversation_step::Message::ThinkingMessage(thinking)) = step.message else {
+            panic!("expected thinking step");
+        };
+        assert_eq!(thinking.text, "reasoning");
+        assert_eq!(thinking.duration_ms, 6_880);
+    }
+}

cursor-server/src/cursor/projection/decode.rs

@@ -0,0 +1,251 @@
+use base64::{engine::general_purpose::STANDARD, Engine};
+use serde_json::Value;
+
+use crate::{
+    model::{
+        CanonicalMessage, ContentPart, MessageContent, Origin, RecoveredToolRound, Role, ToolCall,
+        ToolCallContent, ToolResultContent, ToolRoundAssistant, ToolRoundId,
+    },
+    store::BlobId,
+    Error, Result,
+};
+
+use super::REPLAY_ENVELOPE_PREFIX;
+
+pub fn decode(data: &[u8], internal_id: String) -> Result<CanonicalMessage> {
+    let value: Value = serde_json::from_slice(data)?;
+    let role = match required_string(&value, "role")? {
+        "system" => Role::System,
+        "user" => Role::User,
+        "assistant" => Role::Assistant,
+        "tool" => Role::Tool,
+        role => {
+            return Err(Error::Protocol(format!(
+                "unknown Cursor message role: {role}"
+            )))
+        }
+    };
+    let wire_id = value
+        .get("id")
+        .and_then(Value::as_str)
+        .unwrap_or_default()
+        .to_string();
+    let origin = match role {
+        Role::System => Origin::Prompt,
+        Role::Assistant => Origin::Assistant,
+        Role::Tool => Origin::Tool,
+        Role::User if wire_id.starts_with("runtime:") => Origin::Runtime,
+        Role::User
+            if wire_id.starts_with("request-context:")
+                || wire_id.starts_with("selected-context:") =>
+        {
+            Origin::Prompt
+        }
+        Role::User => Origin::User,
+    };
+    let runtime_event_id = wire_id.strip_prefix("runtime:").map(str::to_string);
+    let content = match role {
+        Role::Assistant => decode_assistant(&value, &internal_id)?,
+        Role::Tool => MessageContent::ToolResult(decode_tool_result(&value)?),
+        _ => decode_text(&value)?,
+    };
+    let message_id = if runtime_event_id.is_some() {
+        wire_id
+    } else {
+        internal_id
+    };
+    Ok(CanonicalMessage {
+        message_id,
+        role,
+        origin,
+        content,
+        runtime_event_id,
+    })
+}
+
+pub fn decode_pending(value: &str) -> Result<RecoveredToolRound> {
+    let wire: Value = serde_json::from_str(value)?;
+    let started_at_ms = wire
+        .pointer("/providerOptions/cursor/pendingToolCallStartedAtMs")
+        .and_then(Value::as_u64)
+        .ok_or_else(|| {
+            Error::Protocol("Cursor pending assistant is missing pendingToolCallStartedAtMs".into())
+        })?;
+    let internal_id = format!(
+        "cursor-pending:{}",
+        BlobId::digest(value.as_bytes()).to_base64()
+    );
+    let message = decode(value.as_bytes(), internal_id.clone())?;
+    let MessageContent::Assistant {
+        text,
+        thinking,
+        tool_round_id: _,
+        replay_state,
+        tool_calls,
+    } = message.content
+    else {
+        return Err(Error::Protocol(
+            "Cursor pending message is not an assistant message".into(),
+        ));
+    };
+    if tool_calls.is_empty() {
+        return Err(Error::Protocol(
+            "Cursor resume contains a pending assistant without tool calls".into(),
+        ));
+    }
+    let model_call_id = wire
+        .pointer("/providerOptions/cursor/modelProviderMessageId")
+        .and_then(Value::as_str)
+        .filter(|value| !value.is_empty())
+        .unwrap_or(&internal_id)
+        .to_string();
+    let calls = tool_calls
+        .into_iter()
+        .enumerate()
+        .map(|(index, call)| {
+            Ok(ToolCall {
+                index,
+                call_id: call.call_id,
+                model_call_id: model_call_id.clone(),
+                name: call.name,
+                arguments_text: serde_json::to_string(&call.arguments)?,
+                arguments: call.arguments,
+            })
+        })
+        .collect::<Result<Vec<_>>>()?;
+    Ok(RecoveredToolRound {
+        assistant: ToolRoundAssistant {
+            text,
+            thinking,
+            model_call_id,
+            replay_state,
+        },
+        calls,
+        started_at_ms,
+    })
+}
+
+fn decode_text(value: &Value) -> Result<MessageContent> {
+    let content = value.get("content").unwrap_or(&Value::Null);
+    if let Some(text) = content.as_str() {
+        return Ok(MessageContent::Parts {
+            parts: vec![ContentPart::Text { text: text.into() }],
+        });
+    }
+    let parts = content
+        .as_array()
+        .ok_or_else(|| Error::Protocol("Cursor message content is not an array".into()))?
+        .iter()
+        .map(|part| match part.get("type").and_then(Value::as_str) {
+            Some("text") => Ok(ContentPart::Text {
+                text: required_string(part, "text")?.into(),
+            }),
+            Some("image") => {
+                let mime_type = required_string(part, "mimeType")?;
+                let encoded = required_string(part, "data")?;
+                Ok(ContentPart::Image {
+                    mime_type: mime_type.into(),
+                    data: STANDARD.decode(encoded).map_err(|error| {
+                        Error::Protocol(format!("invalid Cursor image base64: {error}"))
+                    })?,
+                })
+            }
+            Some(kind) => Err(Error::Protocol(format!(
+                "unsupported Cursor message content part: {kind}"
+            ))),
+            None => Err(Error::Protocol(
+                "Cursor message content part is missing type".into(),
+            )),
+        })
+        .collect::<Result<Vec<_>>>()?;
+    Ok(MessageContent::Parts { parts })
+}
+
+fn decode_assistant(value: &Value, internal_id: &str) -> Result<MessageContent> {
+    let mut text = String::new();
+    let mut thinking = String::new();
+    let mut calls = Vec::new();
+    let mut replay_state = None;
+    for part in value
+        .get("content")
+        .and_then(Value::as_array)
+        .into_iter()
+        .flatten()
+    {
+        match part.get("type").and_then(Value::as_str) {
+            Some("text") => {
+                text.push_str(part.get("text").and_then(Value::as_str).unwrap_or_default())
+            }
+            Some("reasoning") => {
+                thinking.push_str(part.get("text").and_then(Value::as_str).unwrap_or_default());
+                if let Some(signature) = part.get("signature").and_then(Value::as_str) {
+                    if replay_state.is_some() {
+                        return Err(Error::Protocol(
+                            "Cursor assistant has multiple reasoning signatures".into(),
+                        ));
+                    }
+                    replay_state = Some(decode_replay_state(signature)?);
+                }
+            }
+            Some("tool-call") => calls.push(ToolCallContent {
+                index: calls.len(),
+                call_id: required_string(part, "toolCallId")?.into(),
+                name: required_string(part, "toolName")?.into(),
+                arguments: part.get("args").cloned().unwrap_or(Value::Null),
+            }),
+            _ => {}
+        }
+    }
+    Ok(MessageContent::Assistant {
+        text,
+        thinking,
+        tool_round_id: (!calls.is_empty())
+            .then(|| ToolRoundId::new(format!("{internal_id}:tool-round"))),
+        replay_state,
+        tool_calls: calls,
+    })
+}
+
+fn decode_replay_state(signature: &str) -> Result<crate::model::ProviderReplayState> {
+    let Some(encoded) = signature.strip_prefix(REPLAY_ENVELOPE_PREFIX) else {
+        return Ok(crate::model::ProviderReplayState {
+            provider_kind: "cursor_opaque".into(),
+            value: Value::String(signature.into()),
+        });
+    };
+    let bytes = STANDARD.decode(encoded).map_err(|error| {
+        Error::Protocol(format!(
+            "invalid Cursor BYOK replay envelope base64: {error}"
+        ))
+    })?;
+    serde_json::from_slice(&bytes)
+        .map_err(|error| Error::Protocol(format!("invalid Cursor BYOK replay envelope: {error}")))
+}
+
+fn decode_tool_result(value: &Value) -> Result<ToolResultContent> {
+    let part = value
+        .get("content")
+        .and_then(Value::as_array)
+        .and_then(|parts| parts.first())
+        .ok_or_else(|| Error::Protocol("Cursor tool message has no result part".into()))?;
+    Ok(ToolResultContent {
+        call_id: required_string(part, "toolCallId")?.into(),
+        name: required_string(part, "toolName")?.into(),
+        content: part
+            .get("result")
+            .and_then(Value::as_str)
+            .unwrap_or_default()
+            .into(),
+        is_error: part
+            .get("isError")
+            .and_then(Value::as_bool)
+            .unwrap_or(false),
+    })
+}
+
+fn required_string<'a>(value: &'a Value, name: &str) -> Result<&'a str> {
+    value
+        .get(name)
+        .and_then(Value::as_str)
+        .ok_or_else(|| Error::Protocol(format!("Cursor message is missing {name}")))
+}

cursor-server/src/cursor/projection/encode.rs

@@ -0,0 +1,264 @@
+use std::collections::HashSet;
+
+use base64::{engine::general_purpose::STANDARD, Engine};
+use serde_json::{json, Map, Value};
+
+use crate::{
+    model::{
+        project_messages, CanonicalMessage, ContentPart, ProjectedContent, ProjectedMessage, Role,
+        ToolCall, ToolCallContent, ToolRoundAssistant,
+    },
+    Error, Result,
+};
+
+use super::REPLAY_ENVELOPE_PREFIX;
+
+pub fn stable_messages(
+    instructions: &str,
+    messages: &[CanonicalMessage],
+    model: &str,
+) -> Result<Vec<Vec<u8>>> {
+    let mut projected = project_messages(messages)?;
+    if !instructions.is_empty() {
+        projected.insert(
+            0,
+            ProjectedMessage {
+                message_id: "system".into(),
+                role: Role::System,
+                content: ProjectedContent::Parts(vec![ContentPart::Text {
+                    text: instructions.into(),
+                }]),
+            },
+        );
+    }
+    projected
+        .iter()
+        .map(|message| serde_json::to_vec(&wire_message(message, model, None)?).map_err(Into::into))
+        .collect::<std::result::Result<_, _>>()
+}
+
+pub fn staged_tool_round(
+    assistant: &ToolRoundAssistant,
+    calls: &[ToolCall],
+    model: &str,
+    allowed_tools: &[String],
+    dynamic_tools: &HashSet<String>,
+    started_at_ms: u64,
+) -> Result<String> {
+    let message = ProjectedMessage {
+        message_id: assistant.model_call_id.clone(),
+        role: Role::Assistant,
+        content: ProjectedContent::Assistant {
+            text: assistant.text.clone(),
+            thinking: assistant.thinking.clone(),
+            replay_state: assistant.replay_state.clone(),
+            calls: calls
+                .iter()
+                .map(|call| ToolCallContent {
+                    index: call.index,
+                    call_id: call.call_id.clone(),
+                    name: call.name.clone(),
+                    arguments: call.arguments.clone(),
+                })
+                .collect(),
+        },
+    };
+    Ok(serde_json::to_string(&wire_message(
+        &message,
+        model,
+        Some(PendingContext {
+            allowed_tools,
+            dynamic_tools,
+            started_at_ms,
+        }),
+    )?)?)
+}
+
+pub fn staged_final(
+    message: &CanonicalMessage,
+    model: &str,
+    allowed_tools: &[String],
+    dynamic_tools: &HashSet<String>,
+    started_at_ms: u64,
+) -> Result<String> {
+    let projected = project_messages(std::slice::from_ref(message))?;
+    let assistant = projected
+        .first()
+        .filter(|message| message.role == Role::Assistant)
+        .ok_or_else(|| {
+            Error::Protocol("final checkpoint stage is not an assistant message".into())
+        })?;
+    Ok(serde_json::to_string(&wire_message(
+        assistant,
+        model,
+        Some(PendingContext {
+            allowed_tools,
+            dynamic_tools,
+            started_at_ms,
+        }),
+    )?)?)
+}
+
+#[derive(Clone, Copy)]
+pub(super) struct PendingContext<'a> {
+    allowed_tools: &'a [String],
+    dynamic_tools: &'a HashSet<String>,
+    started_at_ms: u64,
+}
+
+pub(super) fn wire_message(
+    message: &ProjectedMessage,
+    model: &str,
+    pending: Option<PendingContext<'_>>,
+) -> Result<Value> {
+    let mut root = Map::new();
+    root.insert(
+        "role".into(),
+        Value::String(role_name(&message.role).into()),
+    );
+    root.insert("content".into(), wire_content(&message.content, model)?);
+    root.insert("id".into(), Value::String(wire_message_id(message)));
+    if let ProjectedContent::Assistant { calls, .. } = &message.content {
+        let mut cursor = Map::new();
+        if let Some(pending) = pending {
+            cursor.insert(
+                "pendingToolCallStartedAtMs".into(),
+                json!(pending.started_at_ms),
+            );
+            cursor.insert(
+                "pendingToolExecutionContracts".into(),
+                Value::Object(
+                    calls
+                        .iter()
+                        .map(|call| {
+                            (
+                                call.call_id.clone(),
+                                json!({
+                                    "toolCallId": call.call_id,
+                                    "outerToolName": call.name,
+                                    "toolIdentifier": tool_identifier(&call.name, pending.dynamic_tools),
+                                    "isDynamic": pending.dynamic_tools.contains(&call.name),
+                                    "allowedToolNames": pending.allowed_tools,
+                                }),
+                            )
+                        })
+                        .collect(),
+                ),
+            );
+        }
+        if !cursor.is_empty() {
+            root.insert("providerOptions".into(), json!({"cursor": cursor}));
+        }
+    }
+    Ok(Value::Object(root))
+}
+
+fn tool_identifier(name: &str, dynamic_tools: &HashSet<String>) -> String {
+    if dynamic_tools.contains(name) {
+        return name.into();
+    }
+    match name {
+        "AwaitShell" => "AWAIT".into(),
+        "CallMcpTool" => "MCP".into(),
+        "CreatePlan" => "CREATE_PLAN_V2".into(),
+        "UpdateCurrentStep" => "COMMUNICATE_UPDATE".into(),
+        _ => name
+            .chars()
+            .enumerate()
+            .fold(String::new(), |mut value, (index, character)| {
+                if index > 0 && character.is_ascii_uppercase() {
+                    value.push('_');
+                }
+                value.push(character.to_ascii_uppercase());
+                value
+            }),
+    }
+}
+
+fn wire_message_id(message: &ProjectedMessage) -> String {
+    match &message.content {
+        ProjectedContent::Assistant { .. } => "1".into(),
+        ProjectedContent::ToolResult(result) => result.call_id.clone(),
+        ProjectedContent::Parts(_) => message.message_id.clone(),
+    }
+}
+
+fn wire_content(content: &ProjectedContent, model: &str) -> Result<Value> {
+    Ok(match content {
+        ProjectedContent::Parts(parts) => Value::Array(
+            parts
+                .iter()
+                .map(|part| match part {
+                    ContentPart::Text { text } => json!({"type":"text", "text":text}),
+                    ContentPart::Image { mime_type, data } => json!({
+                        "type":"image",
+                        "data": STANDARD.encode(data),
+                        "mimeType": mime_type,
+                    }),
+                })
+                .collect(),
+        ),
+        ProjectedContent::Assistant {
+            text,
+            thinking,
+            replay_state,
+            calls,
+        } => {
+            let mut parts = Vec::new();
+            if !thinking.is_empty() || replay_state.is_some() {
+                let mut reasoning = json!({
+                    "type": "reasoning",
+                    "text": thinking,
+                    "providerOptions": {"cursor": {"modelName": model}},
+                });
+                if let Some(replay_state) = replay_state {
+                    reasoning["signature"] = Value::String(encode_replay_state(replay_state)?);
+                }
+                parts.push(reasoning);
+            }
+            if !text.is_empty() {
+                parts.push(json!({"type":"text", "text":text}));
+            }
+            parts.extend(calls.iter().map(|call| {
+                json!({
+                    "type": "tool-call",
+                    "toolCallId": call.call_id,
+                    "toolName": call.name,
+                    "args": call.arguments,
+                })
+            }));
+            Value::Array(parts)
+        }
+        ProjectedContent::ToolResult(result) => json!([{
+            "type": "tool-result",
+            "toolCallId": result.call_id,
+            "toolName": result.name,
+            "result": result.content,
+            "experimental_content": [{"type":"text", "text":result.content}],
+            "isError": result.is_error,
+        }]),
+    })
+}
+
+fn encode_replay_state(replay_state: &crate::model::ProviderReplayState) -> Result<String> {
+    if replay_state.provider_kind == "cursor_opaque" {
+        return replay_state
+            .value
+            .as_str()
+            .map(str::to_string)
+            .ok_or_else(|| Error::Protocol("Cursor opaque replay state is not a string".into()));
+    }
+    Ok(format!(
+        "{REPLAY_ENVELOPE_PREFIX}{}",
+        STANDARD.encode(serde_json::to_vec(replay_state)?)
+    ))
+}
+
+fn role_name(role: &Role) -> &'static str {
+    match role {
+        Role::System => "system",
+        Role::User => "user",
+        Role::Assistant => "assistant",
+        Role::Tool => "tool",
+    }
+}

cursor-server/src/cursor/projection/mod.rs

@@ -0,0 +1,10 @@
+mod decode;
+mod encode;
+
+pub use decode::{decode, decode_pending};
+pub use encode::{stable_messages, staged_final, staged_tool_round};
+
+const REPLAY_ENVELOPE_PREFIX: &str = "cursor-byok:v1:";
+
+#[cfg(test)]
+mod tests;

cursor-server/src/cursor/projection/tests.rs

@@ -0,0 +1,211 @@
+use std::collections::HashSet;
+
+use serde_json::{json, Value};
+
+use crate::model::{
+    project_messages, CanonicalMessage, MessageContent, ProjectedContent, ProjectedMessage,
+    ProviderReplayState, Role, ToolCall, ToolResultContent, ToolRoundAssistant,
+};
+
+use super::{decode, decode_pending, encode::wire_message, staged_tool_round};
+
+#[test]
+fn pending_tool_round_is_one_complete_assistant_message_and_round_trips() {
+    let replay_state = ProviderReplayState {
+        provider_kind: "anthropic".into(),
+        value: json!({"blocks":[{"type":"thinking","thinking":"why","signature":"sig"}]}),
+    };
+    let assistant = ToolRoundAssistant {
+        text: "before tools".into(),
+        thinking: "why".into(),
+        model_call_id: "model-call".into(),
+        replay_state: Some(replay_state.clone()),
+    };
+    let calls = vec![
+        ToolCall {
+            index: 0,
+            call_id: "a".into(),
+            model_call_id: "model-call".into(),
+            name: "Read".into(),
+            arguments_text: r#"{"path":"/a"}"#.into(),
+            arguments: json!({"path":"/a"}),
+        },
+        ToolCall {
+            index: 1,
+            call_id: "b".into(),
+            model_call_id: "model-call".into(),
+            name: "Grep".into(),
+            arguments_text: r#"{"pattern":"x"}"#.into(),
+            arguments: json!({"pattern":"x"}),
+        },
+    ];
+    let pending = staged_tool_round(
+        &assistant,
+        &calls,
+        "claude",
+        &["Read".into(), "Grep".into()],
+        &HashSet::new(),
+        42,
+    )
+    .unwrap();
+    let wire: Value = serde_json::from_str(&pending).unwrap();
+    assert_eq!(wire["id"], "1");
+    assert_eq!(
+        wire["providerOptions"]["cursor"]["pendingToolExecutionContracts"]["a"]["toolIdentifier"],
+        "READ"
+    );
+    assert_eq!(wire["role"], "assistant");
+    assert_eq!(
+        wire["providerOptions"]["cursor"]["pendingToolExecutionContracts"]
+            .as_object()
+            .unwrap()
+            .len(),
+        2
+    );
+    assert_eq!(
+        wire["content"]
+            .as_array()
+            .unwrap()
+            .iter()
+            .filter(|part| part["type"] == "tool-call")
+            .count(),
+        2
+    );
+
+    let recovered = decode_pending(&pending).unwrap();
+    assert_eq!(recovered.assistant.replay_state, Some(replay_state));
+    assert_eq!(recovered.calls.len(), 2);
+    assert_eq!(recovered.calls[0].call_id, "a");
+    assert_eq!(recovered.calls[1].call_id, "b");
+}
+
+#[test]
+fn cursor_wire_ids_are_projection_metadata_not_internal_message_ids() {
+    let assistant = ProjectedMessage {
+        message_id: "internal-assistant-id".into(),
+        role: Role::Assistant,
+        content: ProjectedContent::Assistant {
+            text: "done".into(),
+            thinking: String::new(),
+            replay_state: None,
+            calls: Vec::new(),
+        },
+    };
+    let result = ProjectedMessage {
+        message_id: "internal-result-id".into(),
+        role: Role::Tool,
+        content: ProjectedContent::ToolResult(ToolResultContent {
+            call_id: "call-1".into(),
+            name: "Read".into(),
+            content: "ok".into(),
+            is_error: false,
+        }),
+    };
+
+    assert_eq!(wire_message(&assistant, "model", None).unwrap()["id"], "1");
+    assert_eq!(
+        wire_message(&result, "model", None).unwrap()["id"],
+        "call-1"
+    );
+}
+
+#[test]
+fn runtime_wire_identity_survives_checkpoint_hydration() {
+    let wire = json!({
+        "role": "user",
+        "id": "runtime:subagent-completed:child-id",
+        "content": "child completed",
+    });
+    let message = decode(
+        serde_json::to_vec(&wire).unwrap().as_slice(),
+        "cursor-root:blob-id:19".into(),
+    )
+    .unwrap();
+
+    assert_eq!(message.message_id, "runtime:subagent-completed:child-id");
+    assert_eq!(
+        message.runtime_event_id.as_deref(),
+        Some("subagent-completed:child-id")
+    );
+}
+
+#[test]
+fn repeated_cursor_wire_ids_do_not_merge_distinct_tool_rounds() {
+    fn assistant(call_id: &str, internal_id: &str) -> CanonicalMessage {
+        let wire = json!({
+            "role": "assistant",
+            "id": "1",
+            "content": [{
+                "type": "tool-call",
+                "toolCallId": call_id,
+                "toolName": "Read",
+                "args": {"path": format!("/{call_id}")},
+            }],
+        });
+        decode(
+            serde_json::to_vec(&wire).unwrap().as_slice(),
+            internal_id.into(),
+        )
+        .unwrap()
+    }
+    fn result(call_id: &str, internal_id: &str) -> CanonicalMessage {
+        let wire = json!({
+            "role": "tool",
+            "id": call_id,
+            "content": [{
+                "type": "tool-result",
+                "toolCallId": call_id,
+                "toolName": "Read",
+                "result": "ok",
+            }],
+        });
+        decode(
+            serde_json::to_vec(&wire).unwrap().as_slice(),
+            internal_id.into(),
+        )
+        .unwrap()
+    }
+
+    let messages = vec![
+        assistant("a", "cursor-root:a"),
+        result("a", "cursor-root:a-result"),
+        assistant("b", "cursor-root:b"),
+        result("b", "cursor-root:b-result"),
+    ];
+    assert_ne!(messages[0].message_id, messages[2].message_id);
+    let projected = project_messages(&messages).unwrap();
+    assert_eq!(projected.len(), 4);
+    assert!(matches!(
+        &projected[0].content,
+        ProjectedContent::Assistant { calls, .. } if calls[0].call_id == "a"
+    ));
+    assert!(matches!(
+        &projected[2].content,
+        ProjectedContent::Assistant { calls, .. } if calls[0].call_id == "b"
+    ));
+}
+
+#[test]
+fn opaque_cursor_reasoning_signature_round_trips_without_decoding() {
+    let signature = "opaque-url-safe_signature-value";
+    let wire = json!({
+        "role": "assistant",
+        "id": "1",
+        "content": [{"type":"reasoning", "text":"", "signature":signature}],
+    });
+    let message = decode(
+        serde_json::to_vec(&wire).unwrap().as_slice(),
+        "cursor-root:opaque".into(),
+    )
+    .unwrap();
+    let MessageContent::Assistant { replay_state, .. } = &message.content else {
+        panic!("expected assistant");
+    };
+    assert_eq!(
+        replay_state.as_ref().unwrap().provider_kind,
+        "cursor_opaque"
+    );
+    let projected = project_messages(&[message]).unwrap();
+    let encoded = wire_message(&projected[0], "model", None).unwrap();
+    assert_eq!(encoded["content"][0]["signature"], signature);
+}

cursor-server/src/cursor/prompting/assets.rs

@@ -0,0 +1,180 @@
+use std::{path::Path, sync::OnceLock};
+
+use crate::{model::ToolDefinition, Error, Result};
+
+use super::catalog::Catalog;
+
+static EMBEDDED_PROMPTS: include_dir::Dir<'_> =
+    include_dir::include_dir!("$CARGO_MANIFEST_DIR/../prompt/cursor");
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+pub enum Mode {
+    Agent,
+    Ask,
+    Plan,
+    Debug,
+    Multitask,
+    Subagent,
+    Compaction,
+}
+
+impl Mode {
+    pub fn parse(value: &str) -> Result<Self> {
+        match value.to_ascii_lowercase().as_str() {
+            "agent" => Ok(Self::Agent),
+            "ask" => Ok(Self::Ask),
+            "plan" => Ok(Self::Plan),
+            "debug" => Ok(Self::Debug),
+            "multitask" => Ok(Self::Multitask),
+            "subagent" => Ok(Self::Subagent),
+            "compaction" => Ok(Self::Compaction),
+            other => Err(Error::Config(format!("unknown prompt mode: {other}"))),
+        }
+    }
+
+    fn name(self) -> &'static str {
+        match self {
+            Self::Agent => "agent",
+            Self::Ask => "ask",
+            Self::Plan => "plan",
+            Self::Debug => "debug",
+            Self::Multitask => "multitask",
+            Self::Subagent => "subagent",
+            Self::Compaction => "compaction",
+        }
+    }
+
+    fn index(self) -> usize {
+        match self {
+            Self::Agent => 0,
+            Self::Ask => 1,
+            Self::Plan => 2,
+            Self::Debug => 3,
+            Self::Multitask => 4,
+            Self::Subagent => 5,
+            Self::Compaction => 6,
+        }
+    }
+}
+
+#[derive(Clone, Debug)]
+pub struct ModeAssets {
+    pub prompt: String,
+    pub runtime: String,
+    pub tools: Vec<ToolDefinition>,
+}
+
+#[derive(Clone, Debug)]
+pub struct PromptAssets {
+    modes: [ModeAssets; 7],
+}
+
+impl PromptAssets {
+    pub fn load(root: &Path) -> Result<Self> {
+        Self::read(|path| {
+            let path = root.join(path);
+            path.exists()
+                .then(|| std::fs::read_to_string(path).map_err(Error::from))
+                .transpose()
+        })
+    }
+
+    pub fn embedded() -> Result<Self> {
+        Self::read(|path| {
+            EMBEDDED_PROMPTS
+                .get_file(path)
+                .map(|file| {
+                    file.contents_utf8()
+                        .map(str::to_string)
+                        .ok_or_else(|| Error::Config(format!("prompt asset is not UTF-8: {path}")))
+                })
+                .transpose()
+        })
+    }
+
+    fn read(mut asset: impl FnMut(&str) -> Result<Option<String>>) -> Result<Self> {
+        let catalog = Catalog::parse(
+            &asset("tools.json")?
+                .ok_or_else(|| Error::Config("missing Cursor tools.json".into()))?,
+        )?;
+        let mut modes = Vec::with_capacity(7);
+        for mode in [
+            Mode::Agent,
+            Mode::Ask,
+            Mode::Plan,
+            Mode::Debug,
+            Mode::Multitask,
+            Mode::Subagent,
+            Mode::Compaction,
+        ] {
+            let prompt = asset(&format!("{}/prompt.md", mode.name()))?
+                .ok_or_else(|| Error::Config(format!("missing prompt for {mode:?}")))?;
+            let runtime = asset(&format!("{}/runtime.md", mode.name()))?
+                .ok_or_else(|| Error::Config(format!("missing runtime template for {mode:?}")))?;
+            validate_runtime_template(mode, &runtime)?;
+            let manifest = asset(&format!("modes/{}.json", mode.name()))?
+                .ok_or_else(|| Error::Config(format!("missing manifest for {mode:?}")))?;
+            let tools = catalog.select_json(&manifest)?;
+            modes.push(ModeAssets {
+                prompt,
+                runtime,
+                tools,
+            });
+        }
+        Ok(Self {
+            modes: modes
+                .try_into()
+                .map_err(|_| Error::Config("incomplete Cursor prompt mode catalog".into()))?,
+        })
+    }
+
+    pub fn mode(&self, mode: Mode) -> &ModeAssets {
+        &self.modes[mode.index()]
+    }
+}
+
+const RUNTIME_VARIABLES: &[&str] = &[
+    "REQUEST_CONTEXT",
+    "OPEN_FILES",
+    "SELECTED_CONTEXT",
+    "ACTION_CONTEXT",
+    "TIMESTAMP",
+    "USER_QUERY",
+    "DEBUG_SERVER_ENDPOINT",
+    "DEBUG_LOG_PATH",
+    "DEBUG_SESSION_ID",
+];
+
+fn validate_runtime_template(mode: Mode, template: &str) -> Result<()> {
+    let expression = runtime_expression();
+    for capture in expression.captures_iter(template) {
+        let name = &capture[1];
+        if !RUNTIME_VARIABLES.contains(&name) {
+            return Err(Error::Config(format!(
+                "unknown variable in {mode:?} runtime template: {name}"
+            )));
+        }
+    }
+    for required in ["TIMESTAMP", "USER_QUERY"] {
+        let token = format!("{{{{{required}}}}}");
+        if !template.contains(&token) {
+            return Err(Error::Config(format!(
+                "{mode:?} runtime template is missing {token}"
+            )));
+        }
+    }
+    let stripped = expression.replace_all(template, "");
+    if stripped.contains("{{") || stripped.contains("}}") {
+        return Err(Error::Config(format!(
+            "malformed placeholder in {mode:?} runtime template"
+        )));
+    }
+    Ok(())
+}
+
+pub(super) fn runtime_expression() -> &'static regex::Regex {
+    static EXPRESSION: OnceLock<regex::Regex> = OnceLock::new();
+    EXPRESSION.get_or_init(|| {
+        regex::Regex::new(r"\{\{([A-Z_]+)\}\}").expect("valid runtime placeholder expression")
+    })
+}

cursor-server/src/cursor/prompting/catalog.rs

@@ -0,0 +1,93 @@
+use std::collections::HashMap;
+
+use serde::Deserialize;
+use serde_json::Value;
+
+use crate::{model::ToolDefinition, Error, Result};
+
+#[derive(Deserialize)]
+struct Manifest {
+    tools: Vec<ManifestTool>,
+}
+
+#[derive(Deserialize)]
+#[serde(untagged)]
+enum ManifestTool {
+    Name(String),
+    Variant { name: String, variant: String },
+}
+
+pub(super) struct Catalog {
+    tools: HashMap<String, ToolDefinition>,
+    variants: HashMap<String, ToolDefinition>,
+}
+
+impl Catalog {
+    pub(super) fn parse(json: &str) -> Result<Self> {
+        let value: Value = serde_json::from_str(json)?;
+        let tools = value
+            .get("tools")
+            .and_then(Value::as_array)
+            .ok_or_else(|| Error::Config("tools.json is missing tools".into()))?
+            .iter()
+            .map(parse_tool)
+            .map(|result| result.map(|tool| (tool.name.clone(), tool)))
+            .collect::<Result<HashMap<_, _>>>()?;
+        let variants = value
+            .get("variants")
+            .and_then(Value::as_object)
+            .into_iter()
+            .flat_map(|variants| variants.iter())
+            .map(|(name, value)| parse_tool(value).map(|tool| (name.clone(), tool)))
+            .collect::<Result<HashMap<_, _>>>()?;
+        Ok(Self { tools, variants })
+    }
+
+    pub(super) fn select_json(&self, manifest: &str) -> Result<Vec<ToolDefinition>> {
+        let manifest: Manifest = serde_json::from_str(manifest)?;
+        self.select(&manifest)
+    }
+
+    fn select(&self, manifest: &Manifest) -> Result<Vec<ToolDefinition>> {
+        manifest
+            .tools
+            .iter()
+            .map(|entry| match entry {
+                ManifestTool::Name(name) => self.tools.get(name).cloned().ok_or_else(|| {
+                    Error::Config(format!("tool manifest references unknown schema: {name}"))
+                }),
+                ManifestTool::Variant { name, variant } => self
+                    .variants
+                    .get(&format!("{name}.{variant}"))
+                    .cloned()
+                    .ok_or_else(|| {
+                        Error::Config(format!(
+                            "tool manifest references unknown variant: {name}.{variant}"
+                        ))
+                    }),
+            })
+            .collect()
+    }
+}
+
+fn parse_tool(tool: &Value) -> Result<ToolDefinition> {
+    let function = tool
+        .get("function")
+        .ok_or_else(|| Error::Config("tool is missing function".into()))?;
+    Ok(ToolDefinition {
+        name: function
+            .get("name")
+            .and_then(Value::as_str)
+            .ok_or_else(|| Error::Config("tool is missing name".into()))?
+            .into(),
+        description: function
+            .get("description")
+            .and_then(Value::as_str)
+            .ok_or_else(|| Error::Config("tool is missing description".into()))?
+            .into(),
+        parameters: function
+            .get("parameters")
+            .cloned()
+            .ok_or_else(|| Error::Config("tool is missing parameters".into()))?,
+    })
+}

cursor-server/src/cursor/prompting/compiler.rs

@@ -0,0 +1,86 @@
+use std::collections::BTreeMap;
+
+use crate::{
+    model::{PromptSpec, ToolDefinition},
+    Error, Result,
+};
+
+use super::{assets::runtime_expression, Mode, PromptAssets};
+
+#[derive(Clone)]
+pub struct PromptCompiler {
+    assets: PromptAssets,
+}
+
+impl PromptCompiler {
+    pub fn new(assets: PromptAssets) -> Self {
+        Self { assets }
+    }
+
+    pub fn runtime_message(&self, mode: Mode, values: &BTreeMap<&str, String>) -> Result<String> {
+        render(&self.assets.mode(mode).runtime, values)
+    }
+
+    pub fn prompt_spec(
+        &self,
+        mode: Mode,
+        model: &str,
+        dynamic_tools: &[ToolDefinition],
+        suppress_subagent_progress: bool,
+    ) -> Result<PromptSpec> {
+        let mut tools = self.tools(mode, suppress_subagent_progress);
+        let mut dynamic_tools = dynamic_tools.to_vec();
+        dynamic_tools.sort_by(|left, right| left.name.cmp(&right.name));
+        append_dynamic_tools(&mut tools, dynamic_tools)?;
+        Ok(PromptSpec {
+            instructions: self
+                .assets
+                .mode(mode)
+                .prompt
+                .replace("{{FAKE_MODEL_NAME}}", model),
+            tools,
+        })
+    }
+
+    fn tools(&self, mode: Mode, suppress_subagent_progress: bool) -> Vec<ToolDefinition> {
+        let mut tools = self.assets.mode(mode).tools.clone();
+        if mode == Mode::Subagent && suppress_subagent_progress {
+            tools.retain(|tool| tool.name != "UpdateCurrentStep");
+        }
+        tools
+    }
+}
+
+fn render(template: &str, values: &BTreeMap<&str, String>) -> Result<String> {
+    let expression = runtime_expression();
+    let mut output = String::with_capacity(template.len());
+    let mut cursor = 0;
+    for capture in expression.captures_iter(template) {
+        let token = capture.get(0).expect("runtime template token");
+        let name = &capture[1];
+        let value = values
+            .get(name)
+            .ok_or_else(|| Error::Protocol(format!("runtime template value is missing: {name}")))?;
+        output.push_str(&template[cursor..token.start()]);
+        output.push_str(value);
+        cursor = token.end();
+    }
+    output.push_str(&template[cursor..]);
+    Ok(output.trim().to_string())
+}
+
+fn append_dynamic_tools(
+    tools: &mut Vec<ToolDefinition>,
+    additions: Vec<ToolDefinition>,
+) -> Result<()> {
+    for tool in additions {
+        if tools.iter().any(|existing| existing.name == tool.name) {
+            return Err(Error::Protocol(format!(
+                "dynamic MCP tool conflicts with a mode tool: {}",
+                tool.name
+            )));
+        }
+        tools.push(tool);
+    }
+    Ok(())
+}

cursor-server/src/cursor/prompting/derived_state.rs

@@ -0,0 +1,47 @@
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+
+use crate::model::{CanonicalMessage, MessageContent};
+
+#[derive(Clone, Debug, Default, Serialize, Deserialize, PartialEq)]
+pub struct DerivedState {
+    pub todos: Option<Value>,
+    pub plan: Option<Value>,
+}
+
+pub fn fold_derived_state(messages: &[CanonicalMessage]) -> DerivedState {
+    let mut state = DerivedState::default();
+    let mut calls = std::collections::HashMap::<String, (String, Value)>::new();
+    for message in messages {
+        match &message.content {
+            MessageContent::Assistant { tool_calls, .. } => {
+                for call in tool_calls {
+                    calls.insert(
+                        call.call_id.clone(),
+                        (call.name.clone(), call.arguments.clone()),
+                    );
+                }
+            }
+            MessageContent::ToolResult(result) if !result.is_error => {
+                let Some((name, input)) = calls.get(&result.call_id).cloned() else {
+                    continue;
+                };
+                match normalize(&name).as_str() {
+                    "todowrite" | "updatetodos" => state.todos = Some(input),
+                    "createplan" | "updateplan" | "writeplan" => state.plan = Some(input),
+                    _ => {}
+                }
+            }
+            _ => {}
+        }
+    }
+    state
+}
+
+fn normalize(value: &str) -> String {
+    value
+        .chars()
+        .filter(|character| character.is_ascii_alphanumeric())
+        .flat_map(char::to_lowercase)
+        .collect()
+}

cursor-server/src/cursor/prompting/mod.rs

@@ -0,0 +1,8 @@
+mod assets;
+mod catalog;
+mod compiler;
+mod derived_state;
+
+pub use assets::*;
+pub use compiler::*;
+pub use derived_state::*;

cursor-server/src/cursor/proxy.rs

@@ -0,0 +1,242 @@
+use std::time::Instant;
+
+use axum::{
+    body::{to_bytes, Body, Bytes},
+    extract::Extension,
+    http::{header, Request, Response},
+};
+
+use crate::Result;
+
+const CURSOR_UPSTREAM: &str = "https://api2.cursor.sh";
+
+#[derive(Clone)]
+pub struct CursorProxy {
+    client: reqwest::Client,
+    upstream: String,
+}
+
+pub struct BufferedResponse {
+    pub status: axum::http::StatusCode,
+    pub headers: axum::http::HeaderMap,
+    pub body: Bytes,
+}
+
+impl BufferedResponse {
+    pub fn into_response(self) -> Response<Body> {
+        let body = self.body.clone();
+        self.with_body(body)
+    }
+
+    pub fn with_body(self, body: Bytes) -> Response<Body> {
+        let mut response = Response::new(Body::from(body));
+        *response.status_mut() = self.status;
+        *response.headers_mut() = self.headers;
+        response
+    }
+}
+
+impl CursorProxy {
+    pub fn cursor() -> Result<Self> {
+        Self::for_upstream(CURSOR_UPSTREAM)
+    }
+
+    fn for_upstream(upstream: &str) -> Result<Self> {
+        Ok(Self {
+            client: reqwest::Client::builder()
+                .redirect(reqwest::redirect::Policy::none())
+                .build()?,
+            upstream: upstream.trim_end_matches('/').to_owned(),
+        })
+    }
+}
+
+pub async fn forward(
+    Extension(proxy): Extension<CursorProxy>,
+    request: Request<Body>,
+) -> Result<Response<Body>> {
+    let started = Instant::now();
+    let (parts, body) = request.into_parts();
+    let path = parts
+        .uri
+        .path_and_query()
+        .map_or("/", |value| value.as_str());
+    let url = format!("{}{path}", proxy.upstream);
+
+    let mut headers = parts.headers;
+    headers.remove(header::HOST);
+    remove_hop_by_hop_headers(&mut headers);
+
+    let upstream = proxy
+        .client
+        .request(parts.method.clone(), url)
+        .headers(headers)
+        .body(reqwest::Body::wrap_stream(body.into_data_stream()))
+        .send()
+        .await;
+
+    let upstream = match upstream {
+        Ok(response) => response,
+        Err(error) => {
+            tracing::error!(
+                method = %parts.method,
+                path,
+                elapsed_ms = started.elapsed().as_millis(),
+                %error,
+                "Cursor upstream request failed"
+            );
+            return Err(error.into());
+        }
+    };
+
+    let status = upstream.status();
+    let mut response_headers = upstream.headers().clone();
+    remove_hop_by_hop_headers(&mut response_headers);
+    let mut response = Response::new(Body::from_stream(upstream.bytes_stream()));
+    *response.status_mut() = status;
+    *response.headers_mut() = response_headers;
+
+    tracing::info!(
+        method = %parts.method,
+        path,
+        %status,
+        elapsed_ms = started.elapsed().as_millis(),
+        "forwarded Cursor backend request"
+    );
+    Ok(response)
+}
+
+pub async fn forward_buffered(
+    proxy: &CursorProxy,
+    request: Request<Body>,
+) -> Result<BufferedResponse> {
+    let (parts, body) = request.into_parts();
+    let path = parts
+        .uri
+        .path_and_query()
+        .map_or("/", |value| value.as_str());
+    let mut headers = parts.headers;
+    headers.remove(header::HOST);
+    remove_hop_by_hop_headers(&mut headers);
+    headers.insert(
+        "connect-accept-encoding",
+        axum::http::HeaderValue::from_static("identity"),
+    );
+    headers.insert(
+        header::ACCEPT_ENCODING,
+        axum::http::HeaderValue::from_static("identity"),
+    );
+    let body = to_bytes(body, usize::MAX)
+        .await
+        .map_err(|error| crate::Error::Protocol(format!("cannot read request body: {error}")))?;
+    let upstream = proxy
+        .client
+        .request(parts.method, format!("{}{path}", proxy.upstream))
+        .headers(headers)
+        .body(body)
+        .send()
+        .await?;
+    let status = upstream.status();
+    let mut headers = upstream.headers().clone();
+    remove_hop_by_hop_headers(&mut headers);
+    let body = upstream.bytes().await?;
+    Ok(BufferedResponse {
+        status,
+        headers,
+        body,
+    })
+}
+
+fn remove_hop_by_hop_headers(headers: &mut axum::http::HeaderMap) {
+    let connection_headers = headers
+        .get(header::CONNECTION)
+        .and_then(|value| value.to_str().ok())
+        .map(|value| {
+            value
+                .split(',')
+                .map(str::trim)
+                .filter(|name| !name.is_empty())
+                .map(str::to_owned)
+                .collect::<Vec<_>>()
+        })
+        .unwrap_or_default();
+    for name in connection_headers {
+        headers.remove(name);
+    }
+    for name in [
+        header::CONNECTION,
+        header::PROXY_AUTHENTICATE,
+        header::PROXY_AUTHORIZATION,
+        header::TE,
+        header::TRAILER,
+        header::TRANSFER_ENCODING,
+        header::UPGRADE,
+    ] {
+        headers.remove(name);
+    }
+    headers.remove("keep-alive");
+}
+
+#[cfg(test)]
+mod tests {
+    use axum::{
+        body::{to_bytes, Body},
+        extract::Extension,
+        http::{header, Request, StatusCode},
+        response::IntoResponse,
+        routing::any,
+        Router,
+    };
+    use tower::ServiceExt;
+
+    use super::{forward, CursorProxy};
+
+    #[tokio::test]
+    async fn preserves_request_and_response() {
+        let upstream = Router::new().route(
+            "/unknown",
+            any(|request: Request<Body>| async move {
+                let method = request.method().clone();
+                let query = request.uri().query().unwrap_or_default().to_owned();
+                let marker = request.headers()["x-marker"].clone();
+                let body = to_bytes(request.into_body(), usize::MAX).await.unwrap();
+                (
+                    StatusCode::CREATED,
+                    [(header::CONTENT_TYPE, "application/proto")],
+                    format!(
+                        "{method} {query} {} {}",
+                        marker.to_str().unwrap(),
+                        String::from_utf8_lossy(&body)
+                    ),
+                )
+                    .into_response()
+            }),
+        );
+        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let address = listener.local_addr().unwrap();
+        let server = tokio::spawn(async move { axum::serve(listener, upstream).await.unwrap() });
+        let proxy = CursorProxy::for_upstream(&format!("http://{address}")).unwrap();
+        let app = Router::new().fallback(forward).layer(Extension(proxy));
+
+        let response = app
+            .oneshot(
+                Request::put("/unknown?a=1")
+                    .header("x-marker", "kept")
+                    .body(Body::from("payload"))
+                    .unwrap(),
+            )
+            .await
+            .unwrap();
+
+        assert_eq!(response.status(), StatusCode::CREATED);
+        assert_eq!(
+            response.headers()[header::CONTENT_TYPE],
+            "application/proto"
+        );
+        assert_eq!(
+            to_bytes(response.into_body(), usize::MAX).await.unwrap(),
+            "PUT a=1 kept payload"
+        );
+        server.abort();
+    }
+}

cursor-server/src/cursor/request/background.rs

@@ -0,0 +1,204 @@
+use std::collections::BTreeSet;
+
+use crate::{cursor::proto::agent::v1 as pb, Error, Result};
+
+pub(super) const FOLLOW_UP: &str = concat!(
+    "Perform any necessary follow-up actions in response to the subagent completion above. ",
+    "If no follow-up work is needed, no further action is required. ",
+    "If you mention an agent or subagent in your response, link it with the `[Name](id)` ",
+    "Don't use generic label such as `[agent]`, `[worker]`, or `[subagent]`. ",
+    "For cloud subagents, when the agent has edited code, link to `[Review](bc-id#changes)`, ",
+    "or, if you know the exact added and deleted line counts, `[Review +A −D](bc-id#changes)`, ",
+    "replacing A and D with those counts. Never write A or D literally. ",
+    "Use `[Try Live](bc-id#desktop)` only when the agent used computer use. ",
+    "Don't repeat the same confirmation every time."
+);
+
+#[derive(Debug)]
+pub(super) struct Projection {
+    pub context: String,
+    pub turn_user: pb::UserMessage,
+}
+
+pub(super) fn project(
+    action: &pb::BackgroundTaskCompletionAction,
+    mode: i32,
+) -> Result<Projection> {
+    if action.completions.is_empty() {
+        return Err(Error::Protocol(
+            "background task completion action contains no completion".into(),
+        ));
+    }
+
+    let mut ids = BTreeSet::new();
+    let mut contexts = Vec::with_capacity(action.completions.len());
+    for completion in &action.completions {
+        let kind = pb::BackgroundTaskKind::try_from(completion.kind).map_err(|_| {
+            Error::Protocol(format!("unknown background task kind: {}", completion.kind))
+        })?;
+        if kind != pb::BackgroundTaskKind::Subagent {
+            return Err(Error::Protocol(format!(
+                "unsupported background task completion kind: {}",
+                kind.as_str_name()
+            )));
+        }
+        let reason =
+            pb::BackgroundTaskCompletionReason::try_from(completion.reason).map_err(|_| {
+                Error::Protocol(format!(
+                    "unknown background task completion reason: {}",
+                    completion.reason
+                ))
+            })?;
+        if reason != pb::BackgroundTaskCompletionReason::TaskFinished {
+            return Err(Error::Protocol(format!(
+                "subagent notification is not a finished task: {}",
+                reason.as_str_name()
+            )));
+        }
+        let id = completion
+            .subagent_id
+            .as_deref()
+            .filter(|id| !id.is_empty())
+            .ok_or_else(|| {
+                Error::Protocol("background subagent completion has no subagent_id".into())
+            })?;
+        if completion.task_id.is_empty() || completion.title.is_empty() {
+            return Err(Error::Protocol(
+                "background subagent completion requires task_id and title".into(),
+            ));
+        }
+        if !ids.insert(id) {
+            return Err(Error::Protocol(format!(
+                "duplicate background subagent completion: {id}"
+            )));
+        }
+        contexts.push(completion_context(completion, id)?);
+    }
+
+    let first = &action.completions[0];
+    let message_id = ids.iter().copied().collect::<Vec<_>>().join(":");
+    Ok(Projection {
+        context: contexts.join("\n\n"),
+        turn_user: pb::UserMessage {
+            text: FOLLOW_UP.into(),
+            message_id: format!("subagent-completed:{message_id}"),
+            mode,
+            is_simulated_msg: Some(true),
+            simulated_msg_reason: Some(pb::SimulatedMsgReason::BackgroundTaskCompletion as i32),
+            simulated_message_metadata: Some(pb::user_message::SimulatedMessageMetadata {
+                title: Some(first.title.clone()),
+                task_id: Some(first.task_id.clone()),
+                ..Default::default()
+            }),
+            ..Default::default()
+        },
+    })
+}
+
+fn completion_context(completion: &pb::BackgroundTaskCompletion, id: &str) -> Result<String> {
+    let status = pb::BackgroundTaskStatus::try_from(completion.status).map_err(|_| {
+        Error::Protocol(format!(
+            "unknown background task status: {}",
+            completion.status
+        ))
+    })?;
+    if status == pb::BackgroundTaskStatus::Unspecified {
+        return Err(Error::Protocol(
+            "background subagent completion has unspecified status".into(),
+        ));
+    }
+    let mut fields = vec![
+        format!("Title: {}", completion.title),
+        format!("Subagent ID: {id}"),
+        format!("Status: {}", status.as_str_name()),
+    ];
+    if let Some(tool_call_id) = completion
+        .tool_call_id
+        .as_deref()
+        .filter(|value| !value.is_empty())
+    {
+        fields.push(format!("Tool call ID: {tool_call_id}"));
+    }
+    if let Some(output_path) = completion
+        .output_path
+        .as_deref()
+        .filter(|value| !value.is_empty())
+    {
+        fields.push(format!("Output path: {output_path}"));
+    }
+    if let Some(detail) = completion
+        .detail
+        .as_deref()
+        .filter(|value| !value.is_empty())
+    {
+        fields.push(detail.into());
+    }
+    Ok(format!(
+        "<background_task_completion>\n{}\n</background_task_completion>",
+        fields.join("\n")
+    ))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn finished_subagent_becomes_an_idempotent_user_runtime_event() {
+        let action = pb::BackgroundTaskCompletionAction {
+            completions: vec![completion()],
+        };
+        let projection = project(&action, pb::AgentMode::Multitask as i32).unwrap();
+
+        assert!(projection.context.contains("Subagent ID: child-id"));
+        assert!(projection.context.contains("child result"));
+
+        assert_eq!(projection.turn_user.text, FOLLOW_UP);
+        assert_eq!(projection.turn_user.is_simulated_msg, Some(true));
+        assert_eq!(
+            projection.turn_user.simulated_msg_reason,
+            Some(pb::SimulatedMsgReason::BackgroundTaskCompletion as i32)
+        );
+    }
+
+    #[test]
+    fn completion_requires_the_captured_subagent_identity_and_terminal_reason() {
+        let mut value = completion();
+        value.subagent_id = None;
+        assert!(project(
+            &pb::BackgroundTaskCompletionAction {
+                completions: vec![value]
+            },
+            pb::AgentMode::Agent as i32
+        )
+        .unwrap_err()
+        .to_string()
+        .contains("subagent_id"));
+
+        let mut value = completion();
+        value.reason = pb::BackgroundTaskCompletionReason::TaskProgress as i32;
+        assert!(project(
+            &pb::BackgroundTaskCompletionAction {
+                completions: vec![value]
+            },
+            pb::AgentMode::Agent as i32
+        )
+        .unwrap_err()
+        .to_string()
+        .contains("not a finished task"));
+    }
+
+    fn completion() -> pb::BackgroundTaskCompletion {
+        pb::BackgroundTaskCompletion {
+            task_id: "child-id".into(),
+            kind: pb::BackgroundTaskKind::Subagent as i32,
+            status: pb::BackgroundTaskStatus::Success as i32,
+            title: "Inspect protocol".into(),
+            detail: Some("child result".into()),
+            reason: pb::BackgroundTaskCompletionReason::TaskFinished as i32,
+            subagent_id: Some("child-id".into()),
+            tool_call_id: Some("task-call".into()),
+            ..Default::default()
+        }
+    }
+}

cursor-server/src/cursor/request/context.rs

@@ -0,0 +1,369 @@
+use std::collections::BTreeMap;
+
+use prost::Message;
+use serde_json::Value;
+
+use crate::{
+    cursor::{blob_sync::BlobSynchronizer, proto::agent::v1 as pb},
+    model::ToolDefinition,
+    store::BlobId,
+    Error, Result,
+};
+
+pub async fn hydrate(
+    request: &pb::AgentRunRequest,
+    blobs: &BlobSynchronizer,
+) -> Result<pb::RequestContext> {
+    let mut context = request_context(request).cloned().unwrap_or_default();
+    let Some(parts) = request
+        .action
+        .as_ref()
+        .and_then(|action| action.request_context_parts.as_ref())
+    else {
+        return Ok(context);
+    };
+
+    if let Some(part) = decode_part::<pb::RequestContextRulesPart>(
+        "rules",
+        &parts.rules_blob_id,
+        parts.rules_byte_length,
+        blobs,
+    )
+    .await?
+    {
+        context.rules = part.rules;
+        context.non_file_rules = part.non_file_rules;
+        context.cloud_rule = part.cloud_rule;
+    }
+    if let Some(part) = decode_part::<pb::RequestContextSkillsPart>(
+        "skills",
+        &parts.skills_blob_id,
+        parts.skills_byte_length,
+        blobs,
+    )
+    .await?
+    {
+        context.agent_skills = part.agent_skills;
+        context.skill_options = part.skill_options;
+    }
+    if let Some(part) = decode_part::<pb::RequestContextSubagentsPart>(
+        "subagents",
+        &parts.subagents_blob_id,
+        parts.subagents_byte_length,
+        blobs,
+    )
+    .await?
+    {
+        context.custom_subagents = part.custom_subagents;
+    }
+    if let Some(part) = decode_part::<pb::RequestContextMcpsPart>(
+        "MCP",
+        &parts.mcps_blob_id,
+        parts.mcps_byte_length,
+        blobs,
+    )
+    .await?
+    {
+        context.tools = part.tools;
+        context.mcp_instructions = part.mcp_instructions;
+        context.mcp_file_system_options = part.mcp_file_system_options;
+        context.mcp_meta_tool_options = part.mcp_meta_tool_options;
+    }
+    Ok(context)
+}
+
+async fn decode_part<T: Message + Default>(
+    name: &str,
+    raw_id: &[u8],
+    expected_length: u32,
+    blobs: &BlobSynchronizer,
+) -> Result<Option<T>> {
+    if raw_id.is_empty() {
+        if expected_length != 0 {
+            return Err(Error::Protocol(format!(
+                "{name} context has a byte length but no BlobID"
+            )));
+        }
+        return Ok(None);
+    }
+    let id = BlobId::from_bytes(raw_id)?;
+    let data = blobs.get(&id).await?.ok_or_else(|| {
+        Error::Protocol(format!(
+            "{name} context Blob is missing: {}",
+            id.to_base64()
+        ))
+    })?;
+    if data.len() != expected_length as usize {
+        return Err(Error::Protocol(format!(
+            "{name} context Blob length mismatch: expected {expected_length}, got {}",
+            data.len()
+        )));
+    }
+    T::decode(data.as_slice())
+        .map(Some)
+        .map_err(|error| Error::Protocol(format!("invalid {name} context Blob: {error}")))
+}
+
+pub fn request_context(request: &pb::AgentRunRequest) -> Option<&pb::RequestContext> {
+    let action = request.action.as_ref()?;
+    action
+        .request_context_parts
+        .as_ref()
+        .and_then(|parts| parts.dynamic_context.as_ref())
+        .or_else(|| match action.action.as_ref()? {
+            pb::conversation_action::Action::UserMessageAction(action) => {
+                action.request_context.as_ref()
+            }
+            _ => None,
+        })
+}
+
+pub fn compile_context(context: &pb::RequestContext, today: &str) -> String {
+    let mut sections = Vec::new();
+    let mut transcripts = None;
+    if let Some(env) = &context.env {
+        let workspace = env
+            .workspace_paths
+            .first()
+            .map(String::as_str)
+            .unwrap_or("");
+        let repo = context.git_repos.iter().find(|repo| repo.path == workspace);
+        sections.push(format!(
+            "<user_info>\nOS Version: {}\n\nShell: {}\n\nWorkspace Path: {}\n\nIs directory a git repo: {}\n\nTerminals folder: {}\n\nToday's date: {}\n\nNote: Prefer using absolute paths over relative paths as tool call args when possible.\n</user_info>",
+            env.os_version,
+            env.shell,
+            workspace,
+            repo.map(|repo| format!("Yes, at {}", repo.path)).unwrap_or_else(|| "No".into()),
+            env.terminals_folder,
+            today,
+        ));
+        if !env.agent_transcripts_folder.is_empty() {
+            transcripts = Some(format!(
+                "<agent_transcripts>\nAgent transcripts (past chats) live in {}. They have names like <uuid>.jsonl, cite parent chat transcripts to the user as [<title for chat <=6 words>\n](<uuid excluding .jsonl>). Don't discuss the folder structure.\n</agent_transcripts>",
+                env.agent_transcripts_folder
+            ));
+        }
+    }
+    sections.extend(context.git_repos.iter().map(|repo| {
+        format!(
+            "<git_status>\nThis is the git status at the start of the conversation. Note that this status is a snapshot in time, and will not update during the conversation.\n\n\nGit repo: {}\n\n```\n{}\n```\n</git_status>",
+            repo.path, repo.status
+        )
+    }));
+    sections.extend(transcripts);
+    let mut rules = context
+        .rules
+        .iter()
+        .chain(context.non_file_rules.iter())
+        .map(|rule| format!("<user_rule>{}</user_rule>", rule.content))
+        .collect::<Vec<_>>();
+    rules.extend(
+        context
+            .cloud_rule
+            .iter()
+            .map(|rule| format!("<user_rule>{rule}</user_rule>")),
+    );
+    if !rules.is_empty() {
+        sections.push(format!("<rules>\n{}\n</rules>", rules.join("\n")));
+    }
+    let skills = context
+        .agent_skills
+        .iter()
+        .filter(|skill| !skill.disable_model_invocation)
+        .map(|skill| {
+            format!(
+                "<agent_skill fullPath=\"{}\">{}</agent_skill>",
+                xml(&skill.full_path),
+                skill.description
+            )
+        })
+        .collect::<Vec<_>>();
+    if !skills.is_empty() {
+        sections.push(format!(
+            "<agent_skills>\n<available_skills>\n{}\n</available_skills>\n</agent_skills>",
+            skills.join("\n")
+        ));
+    }
+    let subagents = context
+        .custom_subagents
+        .iter()
+        .map(|agent| {
+            format!(
+                "<subagent name=\"{}\">{}</subagent>",
+                xml(&agent.name),
+                agent.description
+            )
+        })
+        .collect::<Vec<_>>();
+    if !subagents.is_empty() {
+        sections.push(format!(
+            "<subagents>\n{}\n</subagents>",
+            subagents.join("\n")
+        ));
+    }
+    if let Some(options) = &context.mcp_meta_tool_options {
+        let servers = options
+            .mcp_descriptors
+            .iter()
+            .map(|server| {
+                let tools = server
+                    .tools
+                    .iter()
+                    .map(|tool| tool.tool_name.as_str())
+                    .collect::<Vec<_>>()
+                    .join(", ");
+                format!(
+                    "<mcp_meta_tool_server name=\"{}\" tools=\"{}\"{} />",
+                    xml(&server.server_identifier),
+                    xml(&tools),
+                    server
+                        .server_use_instructions
+                        .as_deref()
+                        .filter(|value| !value.is_empty())
+                        .map(|value| format!(" serverUseInstructions=\"{}\"", xml(value)))
+                        .unwrap_or_default()
+                )
+            })
+            .collect::<Vec<_>>();
+        if !servers.is_empty() {
+            sections.push(format!(
+                "<mcp_meta_tools>\n<mcp_meta_tool_servers>\n{}\n</mcp_meta_tool_servers>\n</mcp_meta_tools>",
+                servers.join("\n")
+            ));
+        }
+    }
+    sections.join("\n\n")
+}
+
+pub fn selected_context(user: &pb::UserMessage) -> Option<String> {
+    let selected = user.selected_context.as_ref()?;
+    let mut sections = selected.extra_context.clone();
+    sections.extend(
+        selected
+            .files
+            .iter()
+            .map(|file| format!("<file path=\"{}\">\n{}\n</file>", file.path, file.content)),
+    );
+    sections.extend(
+        selected
+            .code_selections
+            .iter()
+            .map(|value| format!("<code path=\"{}\">\n{}\n</code>", value.path, value.content)),
+    );
+    sections.extend(selected.terminals.iter().map(|value| {
+        format!(
+            "<terminal title=\"{}\">\n{}\n</terminal>",
+            value.title.as_deref().unwrap_or_default(),
+            value.content
+        )
+    }));
+    sections.extend(selected.terminal_selections.iter().map(|value| {
+        format!(
+            "<terminal_selection title=\"{}\">\n{}\n</terminal_selection>",
+            value.title.as_deref().unwrap_or_default(),
+            value.content
+        )
+    }));
+    sections.extend(selected.cursor_rules.iter().filter_map(|value| {
+        value.rule.as_ref().map(|rule| {
+            format!(
+                "<rule path=\"{}\">\n{}\n</rule>",
+                rule.full_path, rule.content
+            )
+        })
+    }));
+    sections.extend(selected.cursor_commands.iter().map(|value| {
+        format!(
+            "<command name=\"{}\">\n{}\n</command>",
+            value.name, value.content
+        )
+    }));
+    sections.extend(selected.selected_skills.iter().map(|value| {
+        format!(
+            "<skill path=\"{}\">\n{}\n{}\n</skill>",
+            value.full_path, value.description, value.content
+        )
+    }));
+    sections.extend(selected.external_links.iter().map(|value| {
+        format!(
+            "External link: {}{}",
+            value.url,
+            value
+                .pdf_content
+                .as_deref()
+                .map(|content| format!("\n{content}"))
+                .unwrap_or_default()
+        )
+    }));
+    Some(sections.join("\n\n"))
+}
+
+pub fn dynamic_mcp(
+    request: &pb::AgentRunRequest,
+    context: &pb::RequestContext,
+) -> Result<BTreeMap<String, (pb::McpToolDefinition, ToolDefinition)>> {
+    let direct = request
+        .mcp_tools
+        .iter()
+        .flat_map(|tools| tools.mcp_tools.iter());
+    let contextual = context.tools.iter();
+    let mut output = BTreeMap::new();
+    for wire in direct.chain(contextual) {
+        if wire.name.is_empty() {
+            return Err(Error::Protocol(
+                "MCP tool definition is missing name".into(),
+            ));
+        }
+        let parameters = match wire.input_schema_json.as_deref() {
+            Some(json) if !json.trim().is_empty() => serde_json::from_str(json)?,
+            _ => prost_value(wire.input_schema.as_ref().ok_or_else(|| {
+                Error::Protocol(format!("MCP tool {} is missing input schema", wire.name))
+            })?),
+        };
+        let definition = ToolDefinition {
+            name: wire.name.clone(),
+            description: wire.description.clone(),
+            parameters,
+        };
+        if output
+            .insert(wire.name.clone(), (wire.clone(), definition))
+            .is_some()
+        {
+            return Err(Error::Protocol(format!(
+                "duplicate MCP tool definition: {}",
+                wire.name
+            )));
+        }
+    }
+    Ok(output)
+}
+
+fn prost_value(value: &prost_types::Value) -> Value {
+    use prost_types::value::Kind;
+    match value.kind.as_ref() {
+        None | Some(Kind::NullValue(_)) => Value::Null,
+        Some(Kind::NumberValue(value)) => serde_json::Number::from_f64(*value)
+            .map(Value::Number)
+            .unwrap_or(Value::Null),
+        Some(Kind::StringValue(value)) => Value::String(value.clone()),
+        Some(Kind::BoolValue(value)) => Value::Bool(*value),
+        Some(Kind::StructValue(value)) => Value::Object(
+            value
+                .fields
+                .iter()
+                .map(|(key, value)| (key.clone(), prost_value(value)))
+                .collect(),
+        ),
+        Some(Kind::ListValue(value)) => {
+            Value::Array(value.values.iter().map(prost_value).collect())
+        }
+    }
+}
+
+fn xml(value: &str) -> String {
+    value
+        .replace('&', "&amp;")
+        .replace('"', "&quot;")
+        .replace('<', "&lt;")
+        .replace('>', "&gt;")
+}

cursor-server/src/cursor/request/images.rs

@@ -0,0 +1,74 @@
+use crate::{
+    cursor::{blob_sync::BlobSynchronizer, proto::agent::v1 as pb},
+    model::ContentPart,
+    store::BlobId,
+    Error, Result,
+};
+
+pub async fn parts(
+    message: &pb::UserMessage,
+    text: String,
+    blobs: &BlobSynchronizer,
+) -> Result<Vec<ContentPart>> {
+    let mut parts = vec![ContentPart::Text { text }];
+    if let Some(context) = &message.selected_context {
+        for image in &context.selected_images {
+            parts.push(ContentPart::Image {
+                mime_type: image_mime_type(image)?,
+                data: image_data(image, blobs).await?,
+            });
+        }
+    }
+    Ok(parts)
+}
+
+fn image_mime_type(image: &pb::SelectedImage) -> Result<String> {
+    let mime_type = image.mime_type.trim();
+    if !mime_type.starts_with("image/") || mime_type.len() == "image/".len() {
+        return Err(Error::Protocol(format!(
+            "selected image has invalid MIME type: {}",
+            image.mime_type
+        )));
+    }
+    Ok(mime_type.into())
+}
+
+async fn image_data(image: &pb::SelectedImage, blobs: &BlobSynchronizer) -> Result<Vec<u8>> {
+    use pb::selected_image::DataOrBlobId;
+
+    let data = match image.data_or_blob_id.as_ref() {
+        Some(DataOrBlobId::Data(data)) => data.clone(),
+        Some(DataOrBlobId::BlobId(raw_id)) => {
+            let id = BlobId::from_bytes(raw_id)?;
+            blobs.get(&id).await?.ok_or_else(|| {
+                Error::Protocol(format!(
+                    "selected image Blob is missing: {}",
+                    id.to_base64()
+                ))
+            })?
+        }
+        Some(DataOrBlobId::BlobIdWithData(value)) => {
+            let id = BlobId::from_bytes(&value.blob_id)?;
+            if value.data.is_empty() {
+                blobs.get(&id).await?.ok_or_else(|| {
+                    Error::Protocol(format!(
+                        "selected image Blob is missing: {}",
+                        id.to_base64()
+                    ))
+                })?
+            } else {
+                blobs.cache_received(&id, &value.data).await?;
+                value.data.clone()
+            }
+        }
+        None => {
+            return Err(Error::Protocol(
+                "selected image is missing data_or_blob_id".into(),
+            ))
+        }
+    };
+    if data.is_empty() {
+        return Err(Error::Protocol("selected image data is empty".into()));
+    }
+    Ok(data)
+}

cursor-server/src/cursor/request/mod.rs

@@ -0,0 +1,8 @@
+mod background;
+mod context;
+mod images;
+mod model;
+mod prepare;
+mod runtime;
+
+pub use prepare::*;

cursor-server/src/cursor/request/model.rs

@@ -0,0 +1,249 @@
+use crate::{
+    cursor::proto::agent::v1 as pb,
+    model::{ModelLatency, ModelSpec, ReasoningSpec, SubagentKind, SubagentModelOverride},
+    Error, Result,
+};
+
+pub fn requested_model(request: &pb::AgentRunRequest) -> Result<ModelSpec> {
+    let details = request.model_details.as_ref();
+    let model = if let Some(requested) = request.requested_model.as_ref() {
+        from_requested(requested, details)?
+    } else if let Some(model_id) = details
+        .map(|model| model.model_id.as_str())
+        .filter(|model| !model.is_empty())
+    {
+        ModelSpec {
+            model_id: model_id.into(),
+            display_name: details
+                .map(|model| model.display_name.clone())
+                .filter(|name| !name.is_empty()),
+            reasoning: ReasoningSpec {
+                enabled: details.is_some_and(|model| model.thinking_details.is_some()),
+                effort: None,
+            },
+            latency: ModelLatency::Standard,
+            max_output_tokens: None,
+            context_window_tokens: None,
+            extra_params: serde_json::json!({}),
+        }
+    } else {
+        return Err(Error::Protocol("Cursor Run does not select a model".into()));
+    };
+    Ok(model)
+}
+
+pub fn selected_models(request: &pb::AgentRunRequest) -> Result<Vec<ModelSpec>> {
+    request
+        .selected_subagent_models
+        .iter()
+        .enumerate()
+        .map(|(index, model)| {
+            from_requested(model, request.selected_subagent_model_details.get(index))
+        })
+        .collect()
+}
+
+pub fn overrides(
+    request: &pb::AgentRunRequest,
+) -> Result<Vec<(SubagentKind, SubagentModelOverride)>> {
+    request
+        .subagent_model_overrides
+        .iter()
+        .map(|value| {
+            use pb::subagent_model_override::Selection;
+            let kind = subagent_kind(&value.subagent_type);
+            let selection = match value.selection.as_ref() {
+                Some(Selection::Model(model)) => {
+                    SubagentModelOverride::Explicit(from_requested(model, None)?)
+                }
+                Some(Selection::Inherit(true)) => SubagentModelOverride::Inherit,
+                Some(Selection::Disabled(true)) => SubagentModelOverride::Disabled,
+                None | Some(Selection::Inherit(false) | Selection::Disabled(false)) => {
+                    return Err(Error::Protocol(format!(
+                        "Cursor subagent model override {} has no active selection",
+                        value.subagent_type
+                    )))
+                }
+            };
+            Ok((kind, selection))
+        })
+        .collect()
+}
+
+pub fn subagent_kind(value: &str) -> SubagentKind {
+    if value == "generalPurpose" {
+        SubagentKind::GeneralPurpose
+    } else {
+        SubagentKind::Named(value.into())
+    }
+}
+
+fn from_requested(
+    model: &pb::RequestedModel,
+    details: Option<&pb::ModelDetails>,
+) -> Result<ModelSpec> {
+    let mut spec = ModelSpec {
+        model_id: model.model_id.clone(),
+        display_name: details
+            .map(|model| model.display_name.clone())
+            .filter(|name| !name.is_empty()),
+        reasoning: ReasoningSpec {
+            enabled: model.max_mode
+                || details.is_some_and(|model| model.thinking_details.is_some()),
+            effort: None,
+        },
+        latency: ModelLatency::Standard,
+        max_output_tokens: None,
+        context_window_tokens: None,
+        extra_params: serde_json::json!({}),
+    };
+    for parameter in &model.parameters {
+        match parameter.id.as_str() {
+            "effort" | "reasoning" => {
+                let effort = parameter.value.trim();
+                spec.reasoning.effort =
+                    (effort != "none" && !effort.is_empty()).then(|| effort.to_string());
+                spec.reasoning.enabled |= spec.reasoning.effort.is_some();
+            }
+            "thinking" => spec.reasoning.enabled |= parse_bool(parameter)?,
+            "fast" => {
+                if parse_bool(parameter)? {
+                    spec.latency = ModelLatency::Fast;
+                }
+            }
+            "context" => {
+                spec.context_window_tokens =
+                    Some(parse_token_count(&parameter.value).ok_or_else(|| {
+                        Error::Protocol(format!(
+                            "invalid Cursor context token count: {}",
+                            parameter.value
+                        ))
+                    })?);
+            }
+            other => {
+                return Err(Error::Protocol(format!(
+                    "unsupported Cursor model parameter: {other}"
+                )))
+            }
+        }
+    }
+    Ok(spec)
+}
+
+fn parse_bool(parameter: &pb::requested_model::ModelParameterValue) -> Result<bool> {
+    match parameter.value.as_str() {
+        "true" => Ok(true),
+        "false" => Ok(false),
+        _ => Err(Error::Protocol(format!(
+            "invalid Cursor boolean model parameter {}={}",
+            parameter.id, parameter.value
+        ))),
+    }
+}
+
+fn parse_token_count(value: &str) -> Option<u64> {
+    let value = value.trim().to_ascii_lowercase();
+    let (number, multiplier) = match value.chars().last()? {
+        'k' => (&value[..value.len() - 1], 1_000),
+        'm' => (&value[..value.len() - 1], 1_000_000),
+        _ => (value.as_str(), 1),
+    };
+    number.parse::<u64>().ok()?.checked_mul(multiplier)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn requested(id: &str, parameters: &[(&str, &str)]) -> pb::RequestedModel {
+        pb::RequestedModel {
+            model_id: id.into(),
+            parameters: parameters
+                .iter()
+                .map(|(id, value)| pb::requested_model::ModelParameterValue {
+                    id: (*id).into(),
+                    value: (*value).into(),
+                })
+                .collect(),
+            ..Default::default()
+        }
+    }
+
+    #[test]
+    fn cursor_model_parameters_keep_order_and_define_reasoning() {
+        let model = from_requested(
+            &requested("grok-4.6", &[("effort", "xhigh"), ("fast", "false")]),
+            None,
+        )
+        .unwrap();
+        assert_eq!(model.model_id, "grok-4.6");
+        assert!(model.reasoning.enabled);
+        assert_eq!(model.reasoning.effort.as_deref(), Some("xhigh"));
+        assert_eq!(model.latency, ModelLatency::Standard);
+    }
+
+    #[test]
+    fn cursor_reasoning_and_context_metadata_are_normalized() {
+        let model = from_requested(
+            &requested(
+                "gpt-5.6-sol",
+                &[("context", "272k"), ("reasoning", "medium")],
+            ),
+            None,
+        )
+        .unwrap();
+        assert_eq!(model.context_window_tokens, Some(272_000));
+        assert_eq!(model.reasoning.effort.as_deref(), Some("medium"));
+        assert!(model.reasoning.enabled);
+    }
+
+    #[test]
+    fn subagent_override_distinguishes_explicit_inherit_and_disabled() {
+        let request = pb::AgentRunRequest {
+            subagent_model_overrides: vec![
+                pb::SubagentModelOverride {
+                    subagent_type: "explore".into(),
+                    selection: Some(pb::subagent_model_override::Selection::Model(requested(
+                        "claude-opus-5",
+                        &[("thinking", "true")],
+                    ))),
+                },
+                pb::SubagentModelOverride {
+                    subagent_type: "generalPurpose".into(),
+                    selection: Some(pb::subagent_model_override::Selection::Inherit(true)),
+                },
+                pb::SubagentModelOverride {
+                    subagent_type: "shell".into(),
+                    selection: Some(pb::subagent_model_override::Selection::Disabled(true)),
+                },
+            ],
+            ..Default::default()
+        };
+        let overrides = overrides(&request).unwrap();
+        assert!(matches!(
+            &overrides[0],
+            (SubagentKind::Named(name), SubagentModelOverride::Explicit(model))
+                if name == "explore" && model.reasoning.enabled
+        ));
+        assert!(matches!(
+            &overrides[1],
+            (SubagentKind::GeneralPurpose, SubagentModelOverride::Inherit)
+        ));
+        assert!(matches!(
+            &overrides[2],
+            (SubagentKind::Named(name), SubagentModelOverride::Disabled) if name == "shell"
+        ));
+    }
+
+    #[test]
+    fn cursor_only_parameters_do_not_leak_into_model_spec() {
+        let model = from_requested(
+            &requested("grok-4.6", &[("fast", "true"), ("context", "300k")]),
+            None,
+        )
+        .unwrap();
+        assert_eq!(model.latency, ModelLatency::Fast);
+        assert_eq!(model.context_window_tokens, Some(300_000));
+        assert!(from_requested(&requested("grok-4.6", &[("mystery", "x")]), None).is_err());
+    }
+}

cursor-server/src/cursor/request/prepare.rs

@@ -0,0 +1,411 @@
+use std::collections::BTreeMap;
+
+use crate::{
+    cursor::prompting::{Mode, PromptCompiler},
+    cursor::{
+        blob_sync::BlobSynchronizer,
+        checkpoint::CheckpointBuilder,
+        projection,
+        proto::agent::v1 as pb,
+        tools::runtime::{ExecContext, SubagentModel},
+    },
+    model::{
+        CanonicalMessage, ContentPart, ConversationId, MessageContent, Origin, PreparedRun, Role,
+        RunAction, RunId, RunKind,
+    },
+    store::Store,
+    Error, Result,
+};
+
+use super::{background, context, model, runtime};
+
+struct ActionProjection {
+    mode: i32,
+    turn_user: Option<pb::UserMessage>,
+    action_context: String,
+    event_id: Option<String>,
+    input_id: Option<String>,
+    starts_turn: bool,
+}
+
+pub struct CursorRunContext {
+    pub request_id: String,
+    pub mode: i32,
+    pub turn_user: Option<pb::UserMessage>,
+    pub exec: ExecContext,
+    pub dynamic_tools: BTreeMap<String, pb::McpToolDefinition>,
+}
+
+pub(crate) struct PrepareDependencies<'a> {
+    pub compiler: &'a PromptCompiler,
+    pub store: &'a Store,
+    pub checkpoint: &'a CheckpointBuilder,
+    pub blob_sync: &'a BlobSynchronizer,
+}
+
+pub(crate) async fn prepare(
+    request_id: &str,
+    request: &pb::AgentRunRequest,
+    parent: Option<(RunId, String)>,
+    dependencies: PrepareDependencies<'_>,
+) -> Result<(PreparedRun, CursorRunContext)> {
+    let PrepareDependencies {
+        compiler,
+        store,
+        checkpoint,
+        blob_sync,
+    } = dependencies;
+    checkpoint
+        .import_prefetched(&request.pre_fetched_blobs)
+        .await?;
+    let conversation_id = ConversationId::new(
+        request
+            .conversation_id
+            .clone()
+            .unwrap_or_else(|| request_id.into()),
+    );
+    // RunSSE/Bidi request_id identifies this concrete execution attempt. Cursor may
+    // reuse AgentRunRequest.run_id when a queued or subagent-driven attempt resumes.
+    let run_id = RunId::new(request_id);
+    let mut base_messages = if request.conversation_state.is_some() {
+        Some(
+            checkpoint
+                .hydrate_messages(request.conversation_state.as_ref())
+                .await?,
+        )
+    } else {
+        None
+    };
+    let request_context = context::hydrate(request, blob_sync).await?;
+    let ActionProjection {
+        mode: mode_number,
+        turn_user,
+        action_context,
+        event_id,
+        input_id,
+        starts_turn,
+    } = action(request_id, request)?;
+    let mode = if request.subagent_type_name.is_some() {
+        Mode::Subagent
+    } else {
+        mode_from_proto(mode_number)?
+    };
+    let model = model::requested_model(request)?;
+    let dynamic = context::dynamic_mcp(request, &request_context)?;
+    let prompt = compiler.prompt_spec(
+        mode,
+        &model.model_id,
+        &dynamic
+            .values()
+            .map(|(_, definition)| definition.clone())
+            .collect::<Vec<_>>(),
+        request.suppress_subagent_progress_update_tool == Some(true),
+    )?;
+    let proposed_base_revision_id = match base_messages.as_mut() {
+        Some(messages) if !messages.is_empty() => {
+            validate_prompt_root(messages)?;
+            messages.retain(|message| {
+                !(message.role == Role::System && message.origin == Origin::Prompt)
+            });
+            store.import_revision(&conversation_id, messages).await?
+        }
+        Some(_) | None => store.ensure_conversation(&conversation_id).await?,
+    };
+    let base_revision_id = match input_id {
+        Some(input_id) => {
+            store
+                .anchor_input(&conversation_id, &input_id, proposed_base_revision_id)
+                .await?
+        }
+        None => proposed_base_revision_id,
+    };
+    let initial_messages = match (turn_user.as_ref(), event_id) {
+        (Some(user), Some(event_id)) => vec![
+            runtime::compile(
+                event_id,
+                mode,
+                user,
+                &request_context,
+                &action_context,
+                compiler,
+                blob_sync,
+            )
+            .await?,
+        ],
+        (None, None) => Vec::new(),
+        _ => {
+            return Err(Error::Protocol(
+                "Cursor action has an incomplete runtime event".into(),
+            ))
+        }
+    };
+    let action = if starts_turn {
+        RunAction::Start
+    } else {
+        let pending_tool_round = match request
+            .conversation_state
+            .as_ref()
+            .map(|state| state.pending_tool_calls.as_slice())
+            .unwrap_or_default()
+        {
+            [] => None,
+            [pending] => Some(projection::decode_pending(pending)?),
+            pending => {
+                return Err(Error::Protocol(format!(
+                    "Cursor resume contains {} pending assistant messages",
+                    pending.len()
+                )))
+            }
+        };
+        RunAction::Resume { pending_tool_round }
+    };
+    let kind = match (request.subagent_type_name.as_deref(), parent) {
+        (None, _) => RunKind::Root,
+        (Some(name), Some((parent_run_id, parent_tool_call_id))) => RunKind::Subagent {
+            parent_run_id,
+            parent_tool_call_id,
+            kind: model::subagent_kind(name),
+            background: false,
+        },
+        (Some(_), None) => {
+            return Err(Error::Protocol(
+                "subagent Run is missing its parent Run and tool call".into(),
+            ));
+        }
+    };
+    let exec = exec_context(request, &request_context, &conversation_id, &model.model_id);
+    Ok((
+        PreparedRun {
+            run_id,
+            conversation_id,
+            kind,
+            model,
+            prompt,
+            selected_subagent_models: model::selected_models(request)?,
+            subagent_model_overrides: model::overrides(request)?,
+            initial_messages,
+            action,
+            base_revision_id,
+        },
+        CursorRunContext {
+            request_id: request_id.into(),
+            mode: mode_number,
+            turn_user,
+            exec,
+            dynamic_tools: dynamic
+                .into_iter()
+                .map(|(name, (wire, _))| (name, wire))
+                .collect(),
+        },
+    ))
+}
+
+fn validate_prompt_root(messages: &[CanonicalMessage]) -> Result<()> {
+    let prompts = messages
+        .iter()
+        .filter(|message| message.role == Role::System && message.origin == Origin::Prompt)
+        .collect::<Vec<_>>();
+    let [prompt] = prompts.as_slice() else {
+        return Err(Error::Protocol(format!(
+            "Cursor history contains {} system prompt roots",
+            prompts.len()
+        )));
+    };
+    let MessageContent::Parts { parts } = &prompt.content else {
+        return Err(Error::Protocol(
+            "Cursor system prompt root is not textual content".into(),
+        ));
+    };
+    let [ContentPart::Text { .. }] = parts.as_slice() else {
+        return Err(Error::Protocol(
+            "Cursor system prompt root is not one text part".into(),
+        ));
+    };
+    Ok(())
+}
+
+fn action(request_id: &str, request: &pb::AgentRunRequest) -> Result<ActionProjection> {
+    let mode = request
+        .conversation_state
+        .as_ref()
+        .and_then(|state| state.mode)
+        .unwrap_or(pb::AgentMode::Agent as i32);
+    let Some(action) = request
+        .action
+        .as_ref()
+        .and_then(|action| action.action.as_ref())
+    else {
+        return Ok(ActionProjection {
+            mode,
+            turn_user: None,
+            action_context: String::new(),
+            event_id: None,
+            input_id: None,
+            starts_turn: false,
+        });
+    };
+    match action {
+        pb::conversation_action::Action::UserMessageAction(action) => {
+            let user = action.user_message.as_ref().ok_or_else(|| {
+                Error::Protocol("Cursor user message action has no UserMessage".into())
+            })?;
+            if user.message_id.is_empty() {
+                return Err(Error::Protocol(
+                    "Cursor user message action has no message_id".into(),
+                ));
+            }
+            let mut context = action
+                .prepend_user_messages
+                .iter()
+                .map(|message| message.text.trim())
+                .filter(|text| !text.is_empty())
+                .map(str::to_string)
+                .collect::<Vec<_>>();
+            context.extend(
+                user.subagent_system_reminder
+                    .iter()
+                    .filter(|text| !text.is_empty())
+                    .cloned(),
+            );
+            Ok(ActionProjection {
+                mode: user.mode,
+                turn_user: Some(user.clone()),
+                action_context: context.join("\n\n"),
+                event_id: Some(format!("run-request:{request_id}")),
+                input_id: Some(format!("cursor:user:{}", user.message_id)),
+                starts_turn: true,
+            })
+        }
+        pb::conversation_action::Action::BackgroundTaskCompletionAction(action) => {
+            let projection = background::project(action, mode)?;
+            Ok(ActionProjection {
+                mode,
+                action_context: projection.context,
+                event_id: Some(format!("run-request:{request_id}")),
+                input_id: None,
+                turn_user: Some(projection.turn_user),
+                starts_turn: true,
+            })
+        }
+        _ => Ok(ActionProjection {
+            mode,
+            turn_user: None,
+            action_context: String::new(),
+            event_id: None,
+            input_id: None,
+            starts_turn: false,
+        }),
+    }
+}
+
+fn mode_from_proto(mode: i32) -> Result<Mode> {
+    let mode = pb::AgentMode::try_from(mode)
+        .map_err(|_| Error::Protocol(format!("unknown Cursor agent mode: {mode}")))?;
+    match mode {
+        pb::AgentMode::Agent => Ok(Mode::Agent),
+        pb::AgentMode::Ask => Ok(Mode::Ask),
+        pb::AgentMode::Plan => Ok(Mode::Plan),
+        pb::AgentMode::Debug => Ok(Mode::Debug),
+        pb::AgentMode::Multitask => Ok(Mode::Multitask),
+        mode => Err(Error::Protocol(format!(
+            "unsupported Cursor agent mode: {}",
+            mode.as_str_name()
+        ))),
+    }
+}
+
+fn exec_context(
+    request: &pb::AgentRunRequest,
+    request_context: &pb::RequestContext,
+    conversation_id: &ConversationId,
+    model_id: &str,
+) -> ExecContext {
+    let subagent_models = request
+        .subagent_model_overrides
+        .iter()
+        .filter_map(|value| {
+            use pb::subagent_model_override::Selection;
+            let selection = match value.selection.as_ref()? {
+                Selection::Model(model) => SubagentModel::Model(model.model_id.clone()),
+                Selection::Inherit(true) => SubagentModel::Model(model_id.into()),
+                Selection::Disabled(true) => SubagentModel::Disabled,
+                Selection::Inherit(false) | Selection::Disabled(false) => return None,
+            };
+            Some((value.subagent_type.clone(), selection))
+        })
+        .collect();
+    ExecContext {
+        conversation_id: conversation_id.to_string(),
+        root_conversation_id: request
+            .conversation_group_id
+            .clone()
+            .unwrap_or_else(|| conversation_id.to_string()),
+        model_id: model_id.into(),
+        subagent_models,
+        terminals_folder: request_context
+            .env
+            .as_ref()
+            .map(|env| env.terminals_folder.clone())
+            .unwrap_or_default(),
+        admin_command_denylist: request_context.admin_command_denylist.clone(),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn restored_system_root_is_structural_not_bound_to_the_next_model() {
+        let prompt = CanonicalMessage::text(
+            "root",
+            Role::System,
+            Origin::Prompt,
+            "prompt from the previous model",
+        );
+        validate_prompt_root(std::slice::from_ref(&prompt)).unwrap();
+        assert!(validate_prompt_root(&[prompt.clone(), prompt]).is_err());
+    }
+
+    #[test]
+    fn unsupported_cursor_mode_is_not_silently_treated_as_agent() {
+        assert_eq!(
+            mode_from_proto(pb::AgentMode::Agent as i32).unwrap(),
+            Mode::Agent
+        );
+        assert!(mode_from_proto(pb::AgentMode::Project as i32).is_err());
+        assert!(mode_from_proto(99).is_err());
+    }
+
+    #[test]
+    fn current_user_message_consumes_the_mode_instead_of_history_mode() {
+        let request = pb::AgentRunRequest {
+            conversation_state: Some(pb::ConversationStateStructure {
+                mode: Some(pb::AgentMode::Agent as i32),
+                ..Default::default()
+            }),
+            action: Some(pb::ConversationAction {
+                action: Some(pb::conversation_action::Action::UserMessageAction(
+                    pb::UserMessageAction {
+                        user_message: Some(pb::UserMessage {
+                            text: "explain".into(),
+                            message_id: "user-message".into(),
+                            mode: pb::AgentMode::Ask as i32,
+                            ..Default::default()
+                        }),
+                        ..Default::default()
+                    },
+                )),
+                ..Default::default()
+            }),
+            ..Default::default()
+        };
+        let projection = action("request", &request).unwrap();
+        assert_eq!(projection.mode, pb::AgentMode::Ask as i32);
+        assert_eq!(
+            projection.input_id.as_deref(),
+            Some("cursor:user:user-message")
+        );
+        assert_eq!(mode_from_proto(projection.mode).unwrap(), Mode::Ask);
+    }
+}

cursor-server/src/cursor/request/runtime.rs

@@ -0,0 +1,161 @@
+use std::collections::BTreeMap;
+
+use chrono::{Offset, Utc};
+use chrono_tz::Tz;
+
+use crate::{
+    cursor::{
+        blob_sync::BlobSynchronizer,
+        prompting::{Mode, PromptCompiler},
+        proto::agent::v1 as pb,
+    },
+    model::{CanonicalMessage, MessageContent, Origin, Role},
+    Error, Result,
+};
+
+use super::{context, images};
+
+pub async fn compile(
+    event_id: String,
+    mode: Mode,
+    user: &pb::UserMessage,
+    request_context: &pb::RequestContext,
+    action_context: &str,
+    compiler: &PromptCompiler,
+    blobs: &BlobSynchronizer,
+) -> Result<CanonicalMessage> {
+    let time = Time::now(
+        request_context
+            .env
+            .as_ref()
+            .map(|env| env.time_zone.as_str()),
+    )?;
+    let mut values = BTreeMap::from([
+        (
+            "REQUEST_CONTEXT",
+            section(context::compile_context(request_context, &time.today)),
+        ),
+        ("OPEN_FILES", section(open_files(user))),
+        (
+            "SELECTED_CONTEXT",
+            section(
+                context::selected_context(user)
+                    .filter(|value| !value.is_empty())
+                    .map(|value| format!("<selected_context>\n{value}\n</selected_context>"))
+                    .unwrap_or_default(),
+            ),
+        ),
+        ("ACTION_CONTEXT", section(action_context.to_string())),
+        ("TIMESTAMP", time.timestamp),
+        ("USER_QUERY", user.text.clone()),
+        ("DEBUG_SERVER_ENDPOINT", String::new()),
+        ("DEBUG_LOG_PATH", String::new()),
+        ("DEBUG_SESSION_ID", String::new()),
+    ]);
+    if let Some(debug) = &request_context.debug_mode_config {
+        values.insert("DEBUG_SERVER_ENDPOINT", debug.server_endpoint.clone());
+        values.insert("DEBUG_LOG_PATH", debug.log_path.clone());
+        values.insert("DEBUG_SESSION_ID", debug.session_id.clone());
+    }
+    let text = compiler.runtime_message(mode, &values)?;
+    Ok(CanonicalMessage {
+        message_id: format!("runtime:{event_id}"),
+        role: Role::User,
+        origin: Origin::Runtime,
+        content: MessageContent::Parts {
+            parts: images::parts(user, text, blobs).await?,
+        },
+        runtime_event_id: Some(event_id),
+    })
+}
+
+fn section(value: String) -> String {
+    let value = value.trim();
+    if value.is_empty() {
+        String::new()
+    } else {
+        format!("{value}\n\n")
+    }
+}
+
+fn open_files(user: &pb::UserMessage) -> String {
+    let Some(ide) = user
+        .selected_context
+        .as_ref()
+        .and_then(|selected| selected.invocation_context.as_ref())
+        .and_then(|invocation| invocation.data.as_ref())
+        .and_then(|data| match data {
+            pb::invocation_context::Data::IdeState(ide) => Some(ide),
+            _ => None,
+        })
+    else {
+        return String::new();
+    };
+    if ide.visible_files.is_empty() && ide.recently_viewed_files.is_empty() {
+        return String::new();
+    }
+
+    let mut output = String::from("<open_and_recently_viewed_files>\n");
+    if !ide.recently_viewed_files.is_empty() {
+        output.push_str("Recently viewed files (recent at the top, oldest at the bottom):\n");
+        for file in &ide.recently_viewed_files {
+            output.push_str(&format!(
+                "- {} (total lines: {})\n",
+                file.path, file.total_lines
+            ));
+        }
+        output.push('\n');
+    }
+    if !ide.visible_files.is_empty() {
+        output.push_str("Files that are currently open and visible in the user's IDE:\n");
+        for (index, file) in ide.visible_files.iter().enumerate() {
+            output.push_str(&format!("- {} (", file.path));
+            if index == 0 {
+                output.push_str("currently focused file");
+                if let Some(cursor) = &file.cursor_position {
+                    output.push_str(&format!(", cursor is on line {}", cursor.line));
+                }
+                output.push_str(&format!(", total lines: {}", file.total_lines));
+            } else {
+                output.push_str(&format!("total lines: {}", file.total_lines));
+            }
+            output.push_str(")\n");
+        }
+        output.push('\n');
+    }
+    output.push_str(
+        "Note: these files may or may not be relevant to the current conversation. Use the read file tool if you need to get the contents of some of them.\n</open_and_recently_viewed_files>",
+    );
+    output
+}
+
+struct Time {
+    timestamp: String,
+    today: String,
+}
+
+impl Time {
+    fn now(time_zone: Option<&str>) -> Result<Self> {
+        let zone = match time_zone.filter(|value| !value.is_empty()) {
+            Some(value) => value
+                .parse::<Tz>()
+                .map_err(|_| Error::Protocol(format!("invalid Cursor time zone: {value}")))?,
+            None => chrono_tz::UTC,
+        };
+        let now = Utc::now().with_timezone(&zone);
+        let offset = now.offset().fix().local_minus_utc();
+        let sign = if offset < 0 { '-' } else { '+' };
+        let offset = offset.unsigned_abs();
+        let hours = offset / 3600;
+        let minutes = (offset % 3600) / 60;
+        let utc = if minutes == 0 {
+            format!("UTC{sign}{hours}")
+        } else {
+            format!("UTC{sign}{hours}:{minutes:02}")
+        };
+        Ok(Self {
+            timestamp: format!("{} ({utc})", now.format("%A, %b %-d, %Y, %-I:%M %p")),
+            today: now.format("%A %b %-d,\n%Y").to_string(),
+        })
+    }
+}

cursor-server/src/cursor/run_sse.rs

@@ -6,9 +6,9 @@ use bytes::Bytes;
 use tokio_stream::wrappers::UnboundedReceiverStream;
 use tokio_stream::StreamExt;
 
-use crate::{run::RunRegistry, Result};
+use crate::{cursor::CursorSessionRegistry, Result};
 
-pub async fn stream(registry: &RunRegistry, request_id: &str) -> Result<Response<Body>> {
+pub async fn stream(registry: &CursorSessionRegistry, request_id: &str) -> Result<Response<Body>> {
     let receiver = registry.get_or_create(request_id).await?.subscribe();
     let body_stream =
         UnboundedReceiverStream::new(receiver).map(Ok::<Bytes, std::convert::Infallible>);

cursor-server/src/cursor/session.rs

@@ -0,0 +1,496 @@
+use std::collections::{BTreeMap, HashMap, HashSet, VecDeque};
+
+use tokio::sync::oneshot;
+
+use crate::{
+    client::{ClientCommand, ClientEvent, ClientSession, CommitCause},
+    cursor::{
+        checkpoint::{
+            worker::{CheckpointJob, CheckpointKind, CheckpointWorker, FinalCheckpoints},
+            CheckpointBuilder,
+        },
+        interaction,
+        presentation::Presentation,
+        proto::agent::v1 as pb,
+        request::CursorRunContext,
+        tools::{
+            codec,
+            result::{ToolCompletion, ToolResultReceiver},
+            runtime::CursorToolRuntime,
+            stream::ToolCallStream,
+            ToolBatchState, ToolDispatcher,
+        },
+    },
+    model::{ToolCall, ToolRoundId, Usage},
+    run::{RunFailure, RunOutcome},
+    store::{Store, ToolRoundStatus},
+    Error, Result,
+};
+
+use super::CursorSessionHandle;
+
+pub struct CursorSession {
+    handle: CursorSessionHandle,
+    store: Store,
+    context: CursorRunContext,
+    core: ClientSession,
+    tools: ToolDispatcher,
+    results: ToolResultReceiver,
+    checkpoint: CheckpointBuilder,
+    tool_runtime: CursorToolRuntime,
+}
+
+pub(crate) struct CursorSessionRuntime {
+    pub tools: ToolDispatcher,
+    pub results: ToolResultReceiver,
+    pub checkpoint: CheckpointBuilder,
+    pub tool_runtime: CursorToolRuntime,
+}
+
+impl CursorSession {
+    pub(crate) fn new(
+        handle: CursorSessionHandle,
+        store: Store,
+        context: CursorRunContext,
+        core: ClientSession,
+        runtime: CursorSessionRuntime,
+    ) -> Self {
+        Self {
+            handle,
+            store,
+            context,
+            core,
+            tools: runtime.tools,
+            results: runtime.results,
+            checkpoint: runtime.checkpoint,
+            tool_runtime: runtime.tool_runtime,
+        }
+    }
+
+    pub async fn run(mut self) -> Result<()> {
+        let mut worker = CheckpointWorker::spawn(
+            self.store.clone(),
+            self.checkpoint.clone(),
+            self.handle.clone(),
+            self.context.mode,
+        );
+        let mut checkpoint_worker_open = true;
+        let mut calls = BTreeMap::<usize, ToolCall>::new();
+        let mut streams = BTreeMap::<usize, ToolCallStream>::new();
+        let mut completions = HashMap::<String, ToolCompletion>::new();
+        let mut completed = HashSet::<String>::new();
+        let mut response_text = String::new();
+        let mut response_thinking = String::new();
+        let mut active_round = None::<ToolRoundId>;
+        let mut final_checkpoint = None::<FinalCheckpoints>;
+        let mut turn_usage = None::<Usage>;
+        let mut context_tokens = None::<u64>;
+        let mut ready = VecDeque::new();
+        let mut presentation = Presentation::default();
+
+        loop {
+            let input = if let Some(completion) = ready.pop_front() {
+                Input::Completion(completion)
+            } else {
+                tokio::select! {
+                    event = self.core.events.recv() => Input::Event(event),
+                    completion = self.results.recv() => Input::CompletionResult(completion),
+                    failure = worker.failures.recv(), if checkpoint_worker_open => Input::CheckpointFailure(failure),
+                }
+            };
+            match input {
+                Input::CheckpointFailure(Some(error)) => return Err(error),
+                Input::CheckpointFailure(None) => {
+                    checkpoint_worker_open = false;
+                }
+                Input::Completion(completion) => {
+                    self.forward_completion(completion, &mut completions)
+                        .await?;
+                }
+                Input::CompletionResult(Some(result)) => {
+                    self.forward_completion(result?, &mut completions).await?;
+                }
+                Input::CompletionResult(None) => {
+                    return Err(Error::Protocol("tool result channel closed".into()));
+                }
+                Input::Event(None) => {
+                    worker.abort();
+                    return Err(Error::Protocol("core event channel closed".into()));
+                }
+                Input::Event(Some(event)) => match event {
+                    ClientEvent::TextStart => {}
+                    ClientEvent::TextEnd => presentation.finish_text(),
+                    ClientEvent::TextDelta(delta) => {
+                        response_text.push_str(&delta);
+                        presentation.text_delta(&delta);
+                        self.emit_model_event(crate::provider::ModelEvent::TextDelta(delta), "")?;
+                    }
+                    ClientEvent::ThinkingStart => {}
+                    ClientEvent::ThinkingDelta(delta) => {
+                        response_thinking.push_str(&delta);
+                        presentation.thinking_delta(&delta);
+                        self.emit_model_event(
+                            crate::provider::ModelEvent::ThinkingDelta(delta),
+                            "",
+                        )?;
+                    }
+                    ClientEvent::ThinkingEnd { duration } => {
+                        presentation.finish_thinking(duration);
+                        self.handle
+                            .emit(&interaction::thinking_completed(duration))?;
+                    }
+                    ClientEvent::ToolCallStart {
+                        index,
+                        call_id,
+                        name,
+                        model_call_id,
+                    } => {
+                        let call = ToolCall {
+                            index,
+                            call_id: call_id.clone(),
+                            model_call_id: model_call_id.clone(),
+                            name: name.clone(),
+                            arguments_text: String::new(),
+                            arguments: serde_json::Value::Null,
+                        };
+                        self.emit_model_event(
+                            crate::provider::ModelEvent::ToolCallStart {
+                                index,
+                                call_id,
+                                name: name.clone(),
+                            },
+                            &model_call_id,
+                        )?;
+                        streams.insert(index, ToolCallStream::new(&name));
+                        calls.insert(index, call);
+                    }
+                    ClientEvent::ToolCallArgumentsDelta { index, delta } => {
+                        let call = calls.get_mut(&index).ok_or_else(|| {
+                            Error::Protocol(format!("unknown streaming tool index: {index}"))
+                        })?;
+                        call.arguments_text.push_str(&delta);
+                        let stream = streams.get_mut(&index).ok_or_else(|| {
+                            Error::Protocol(format!("missing Cursor tool stream: {index}"))
+                        })?;
+                        for message in stream.arguments_delta(call, &delta)? {
+                            self.handle.emit(&message)?;
+                        }
+                    }
+                    ClientEvent::ToolCallEnd { index } => {
+                        let call = calls.get_mut(&index).ok_or_else(|| {
+                            Error::Protocol(format!("unknown completed tool index: {index}"))
+                        })?;
+                        call.arguments = serde_json::from_str(&call.arguments_text)?;
+                    }
+                    ClientEvent::Usage(usage) => {
+                        if let Some(output_tokens) = usage.output_tokens {
+                            self.handle.emit(&interaction::token_delta(output_tokens))?;
+                        }
+                        context_tokens = usage
+                            .input_tokens
+                            .zip(usage.output_tokens)
+                            .and_then(|(input, output)| input.checked_add(output));
+                        match &mut turn_usage {
+                            Some(total) => *total += usage,
+                            None => turn_usage = Some(usage),
+                        }
+                    }
+                    ClientEvent::ExecuteToolRound {
+                        round_id,
+                        calls: round_calls,
+                    } => {
+                        active_round = Some(round_id);
+                        for dispatched in self
+                            .tools
+                            .start_batch(
+                                &round_calls,
+                                ToolBatchState {
+                                    completed: &completed,
+                                    started: &HashSet::new(),
+                                    response_text: &response_text,
+                                    response_thinking: &response_thinking,
+                                },
+                                &self
+                                    .store
+                                    .load_current_messages(&crate::model::ConversationId::new(
+                                        &self.context.exec.conversation_id,
+                                    ))
+                                    .await?,
+                                &self.context.dynamic_tools,
+                                &self.context.exec,
+                            )
+                            .await?
+                        {
+                            for message in dispatched.messages {
+                                self.handle.emit(&message)?;
+                            }
+                            if let Some(completion) = dispatched.completion {
+                                ready.push_back(completion);
+                            }
+                        }
+                        response_text.clear();
+                        response_thinking.clear();
+                        calls.clear();
+                        streams.clear();
+                    }
+                    ClientEvent::StateCommitted(state) => {
+                        if let CommitCause::ToolRoundStarted(round_id) = &state.cause {
+                            active_round = Some(round_id.clone());
+                        }
+                        let mut tool_round_settled = false;
+                        if let CommitCause::ToolResult { call_id } = &state.cause {
+                            let completion = completions.remove(call_id).ok_or_else(|| {
+                                Error::Protocol(format!(
+                                    "core committed a tool result without typed Cursor state: {call_id}"
+                                ))
+                            })?;
+                            let snapshot = self
+                                .store
+                                .tool_round(active_round.as_ref().ok_or_else(|| {
+                                    Error::Protocol("tool commit has no active round".into())
+                                })?)
+                                .await?
+                                .ok_or_else(|| {
+                                    Error::Store("active tool round disappeared".into())
+                                })?;
+                            let call = snapshot
+                                .calls
+                                .iter()
+                                .find(|call| call.call_id == *call_id)
+                                .ok_or_else(|| {
+                                    Error::Protocol(format!(
+                                        "committed call is absent from tool round: {call_id}"
+                                    ))
+                                })?;
+                            self.handle
+                                .emit(&interaction::tool_completed(call, &completion))?;
+                            presentation.tool_completed(&completion);
+                            completed.insert(call_id.clone());
+                            tool_round_settled = snapshot.status == ToolRoundStatus::Settled;
+                        }
+                        let final_turn = state.cause == CommitCause::FinalTurn;
+                        if final_turn {
+                            if !state.barrier.is_required() {
+                                return Err(Error::Protocol(
+                                    "final state has no completion barrier".into(),
+                                ));
+                            }
+                            let (sender, receiver) = oneshot::channel();
+                            worker
+                                .jobs
+                                .send(CheckpointJob {
+                                    kind: CheckpointKind::Final {
+                                        revision_id: state.revision_id,
+                                        result: sender,
+                                    },
+                                    presentation: presentation.take(),
+                                    context_tokens,
+                                    ready: None,
+                                })
+                                .await
+                                .map_err(|_| Error::Protocol("checkpoint worker closed".into()))?;
+                            match receiver
+                                .await
+                                .map_err(|_| Error::Protocol("checkpoint worker stopped".into()))?
+                            {
+                                Ok(checkpoints) => {
+                                    final_checkpoint = Some(checkpoints);
+                                    state.barrier.complete(Ok(()));
+                                }
+                                Err(error) => {
+                                    state.barrier.complete(Err(error.to_string()));
+                                    return Err(error);
+                                }
+                            }
+                        } else if let CommitCause::ToolRoundStarted(round_id) = &state.cause {
+                            worker
+                                .jobs
+                                .send(CheckpointJob {
+                                    kind: CheckpointKind::ToolStarted {
+                                        round_id: round_id.clone(),
+                                        stable_revision_id: state.revision_id,
+                                    },
+                                    presentation: presentation.take(),
+                                    context_tokens,
+                                    ready: None,
+                                })
+                                .await
+                                .map_err(|_| Error::Protocol("checkpoint worker closed".into()))?;
+                        } else if tool_round_settled {
+                            if !state.barrier.is_required() {
+                                return Err(Error::Protocol(
+                                    "settled tool round has no completion barrier".into(),
+                                ));
+                            }
+                            let (ready, published) = oneshot::channel();
+                            worker
+                                .jobs
+                                .send(CheckpointJob {
+                                    kind: CheckpointKind::ToolSettled(state.revision_id),
+                                    presentation: presentation.take(),
+                                    context_tokens,
+                                    ready: Some(ready),
+                                })
+                                .await
+                                .map_err(|_| Error::Protocol("checkpoint worker closed".into()))?;
+                            let result = published
+                                .await
+                                .map_err(|_| Error::Protocol("checkpoint worker stopped".into()))?
+                                .map_err(Error::Protocol);
+                            match result {
+                                Ok(()) => state.barrier.complete(Ok(())),
+                                Err(error) => {
+                                    state.barrier.complete(Err(error.to_string()));
+                                    return Err(error);
+                                }
+                            }
+                            active_round = None;
+                            self.tool_runtime.clear_completed().await;
+                        } else if !matches!(&state.cause, CommitCause::ToolResult { .. })
+                            && active_round.is_some()
+                        {
+                            let round_id = active_round.clone().ok_or_else(|| {
+                                Error::Protocol("active tool round disappeared".into())
+                            })?;
+                            worker
+                                .jobs
+                                .send(CheckpointJob {
+                                    kind: CheckpointKind::ToolStarted {
+                                        round_id,
+                                        stable_revision_id: state.revision_id,
+                                    },
+                                    presentation: presentation.take(),
+                                    context_tokens,
+                                    ready: None,
+                                })
+                                .await
+                                .map_err(|_| Error::Protocol("checkpoint worker closed".into()))?;
+                        } else if !matches!(&state.cause, CommitCause::ToolResult { .. }) {
+                            let requires_ready = state.barrier.is_required();
+                            let (ready, published) = oneshot::channel();
+                            worker
+                                .jobs
+                                .send(CheckpointJob {
+                                    kind: CheckpointKind::Settled(state.revision_id),
+                                    presentation: presentation.take(),
+                                    context_tokens,
+                                    ready: requires_ready.then_some(ready),
+                                })
+                                .await
+                                .map_err(|_| Error::Protocol("checkpoint worker closed".into()))?;
+                            if requires_ready {
+                                let result = published
+                                    .await
+                                    .map_err(|_| {
+                                        Error::Protocol("checkpoint worker stopped".into())
+                                    })?
+                                    .map_err(Error::Protocol);
+                                match result {
+                                    Ok(()) => state.barrier.complete(Ok(())),
+                                    Err(error) => {
+                                        state.barrier.complete(Err(error.to_string()));
+                                        return Err(error);
+                                    }
+                                }
+                            }
+                        }
+                    }
+                    ClientEvent::Ended(outcome) => {
+                        return match outcome {
+                            RunOutcome::Completed => {
+                                let checkpoints = final_checkpoint.take().ok_or_else(|| {
+                                    Error::Protocol("Completed without final state".into())
+                                })?;
+                                self.handle.emit(&interaction::turn_ended(turn_usage))?;
+                                self.checkpoint
+                                    .publish(&self.handle, &checkpoints.staged)
+                                    .await?;
+                                self.checkpoint
+                                    .publish(&self.handle, &checkpoints.settled)
+                                    .await?;
+                                self.handle.emit(&pb::AgentServerMessage {
+                                    ttft_breakdown: None,
+                                    message: Some(pb::agent_server_message::Message::ConversationCheckpointUpdate(checkpoints.settled)),
+                                })?;
+                                crate::cursor::lifecycle::finish_success(&self.handle);
+                                Ok(())
+                            }
+                            RunOutcome::Cancelled => {
+                                worker.abort();
+                                self.abort_execs().await;
+                                crate::cursor::lifecycle::cancel(&self.handle)
+                            }
+                            RunOutcome::Failed(failure) => {
+                                worker.abort();
+                                self.abort_execs().await;
+                                crate::cursor::lifecycle::fail(&self.handle, &cursor_error(failure))
+                            }
+                        };
+                    }
+                },
+            }
+        }
+    }
+
+    async fn abort_execs(&self) {
+        for id in self.tool_runtime.drain_running().await {
+            let _ = self.handle.emit(&codec::abort(id));
+        }
+    }
+
+    async fn forward_completion(
+        &self,
+        completion: ToolCompletion,
+        completions: &mut HashMap<String, ToolCompletion>,
+    ) -> Result<()> {
+        let result = completion.result();
+        if result.call_id.is_empty() {
+            return Err(Error::Protocol("tool result call_id is empty".into()));
+        }
+        if completions
+            .insert(result.call_id.clone(), completion.clone())
+            .is_some()
+        {
+            return Err(Error::Protocol(format!(
+                "duplicate tool result call_id: {}",
+                result.call_id
+            )));
+        }
+        self.core
+            .commands
+            .send(ClientCommand::ToolResult {
+                call_id: result.call_id.clone(),
+                content: result.content.clone(),
+                is_error: result.is_error,
+            })
+            .await
+            .map_err(|_| Error::RunNotFound(self.context.request_id.clone()))
+    }
+
+    fn emit_model_event(
+        &self,
+        event: crate::provider::ModelEvent,
+        model_call_id: &str,
+    ) -> Result<()> {
+        if let Some(message) = interaction::response_event(&event, model_call_id)? {
+            self.handle.emit(&message)?;
+        }
+        Ok(())
+    }
+}
+
+enum Input {
+    Event(Option<ClientEvent>),
+    Completion(ToolCompletion),
+    CompletionResult(Option<Result<ToolCompletion>>),
+    CheckpointFailure(Option<Error>),
+}
+
+fn cursor_error(failure: RunFailure) -> Error {
+    match failure {
+        RunFailure::Protocol(message) => Error::Protocol(message),
+        RunFailure::Provider(message) => Error::Provider(message),
+        RunFailure::Store(message) => Error::Store(message),
+        RunFailure::Client(message) => Error::Protocol(message),
+    }
+}

cursor-server/src/cursor/sessions.rs

@@ -0,0 +1,237 @@
+use std::{
+    collections::HashMap,
+    sync::{Arc, OnceLock},
+};
+
+use bytes::Bytes;
+use tokio::sync::{mpsc, Mutex};
+use tokio_util::sync::CancellationToken;
+
+use crate::{
+    cursor::prompting::PromptCompiler,
+    cursor::{blob_sync::BlobSynchronizer, proto::agent::v1 as pb},
+    provider::Provider,
+    run::RunRegistry,
+    store::Store,
+    Result,
+};
+
+use super::{
+    actor::{CursorActor, RunDependencies},
+    CursorCommand,
+};
+
+#[derive(Clone)]
+pub struct CursorSessionHandle {
+    request_id: String,
+    commands: mpsc::Sender<CursorCommand>,
+    output: Arc<OutputHub>,
+    cancellation: CancellationToken,
+    parent: Arc<OnceLock<CursorParent>>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct CursorParent {
+    pub run_id: String,
+    pub tool_call_id: String,
+}
+
+impl CursorSessionHandle {
+    pub fn request_id(&self) -> &str {
+        &self.request_id
+    }
+    pub fn subscribe(&self) -> mpsc::UnboundedReceiver<Bytes> {
+        self.output.subscribe()
+    }
+    pub async fn command(&self, command: CursorCommand) -> Result<()> {
+        self.commands
+            .send(command)
+            .await
+            .map_err(|_| crate::Error::RunNotFound(self.request_id.clone()))
+    }
+    pub fn emit_frame(&self, frame: Bytes) {
+        self.output.emit(frame);
+    }
+    pub fn emit(&self, message: &pb::AgentServerMessage) -> Result<()> {
+        self.emit_frame(crate::cursor::connect::encode_message(message)?);
+        Ok(())
+    }
+    pub fn cancel(&self) {
+        self.cancellation.cancel();
+    }
+    pub fn close_output(&self) {
+        self.output.close();
+    }
+    pub fn cancellation(&self) -> CancellationToken {
+        self.cancellation.clone()
+    }
+    pub fn set_parent(&self, parent: CursorParent) -> Result<()> {
+        if parent.run_id.is_empty() || parent.tool_call_id.is_empty() {
+            return Err(crate::Error::Protocol(
+                "Cursor parent run and tool call ids are required".into(),
+            ));
+        }
+        if self.parent.get().is_some_and(|current| current != &parent) {
+            return Err(crate::Error::Protocol(format!(
+                "conflicting parent ids for request {}",
+                self.request_id
+            )));
+        }
+        let _ = self.parent.set(parent);
+        Ok(())
+    }
+    pub fn parent(&self) -> Option<&CursorParent> {
+        self.parent.get()
+    }
+}
+
+#[derive(Default)]
+struct OutputHub {
+    state: parking_lot::Mutex<OutputState>,
+    closed: tokio::sync::Notify,
+}
+
+#[derive(Default)]
+struct OutputState {
+    history: Vec<Bytes>,
+    subscribers: Vec<mpsc::UnboundedSender<Bytes>>,
+    closed: bool,
+}
+
+impl OutputHub {
+    fn emit(&self, frame: Bytes) {
+        let mut state = self.state.lock();
+        if state.closed {
+            return;
+        }
+        state.history.push(frame.clone());
+        state
+            .subscribers
+            .retain(|subscriber| subscriber.send(frame.clone()).is_ok());
+    }
+
+    fn subscribe(&self) -> mpsc::UnboundedReceiver<Bytes> {
+        let (sender, receiver) = mpsc::unbounded_channel();
+        let mut state = self.state.lock();
+        for frame in &state.history {
+            let _ = sender.send(frame.clone());
+        }
+        if !state.closed {
+            state.subscribers.push(sender);
+        }
+        receiver
+    }
+
+    fn close(&self) {
+        let mut state = self.state.lock();
+        state.closed = true;
+        state.subscribers.clear();
+        drop(state);
+        self.closed.notify_waiters();
+    }
+
+    async fn wait_closed(&self) {
+        loop {
+            let notified = self.closed.notified();
+            if self.state.lock().closed {
+                return;
+            }
+            notified.await;
+        }
+    }
+}
+
+#[derive(Clone)]
+pub struct CursorSessionRegistry {
+    inner: Arc<RegistryInner>,
+}
+
+struct RegistryInner {
+    runs: Mutex<HashMap<String, CursorSessionHandle>>,
+    run_registry: RunRegistry,
+    store: Store,
+    provider: Arc<dyn Provider>,
+    compiler: PromptCompiler,
+}
+
+impl CursorSessionRegistry {
+    pub fn store(&self) -> &Store {
+        &self.inner.store
+    }
+
+    pub fn new(
+        store: Store,
+        provider: Arc<dyn Provider>,
+        compiler: PromptCompiler,
+        run_registry: RunRegistry,
+    ) -> Self {
+        Self {
+            inner: Arc::new(RegistryInner {
+                runs: Mutex::new(HashMap::new()),
+                run_registry,
+                store,
+                provider,
+                compiler,
+            }),
+        }
+    }
+
+    pub async fn get_or_create(&self, request_id: &str) -> Result<CursorSessionHandle> {
+        if let Some(handle) = self.inner.runs.lock().await.get(request_id).cloned() {
+            return Ok(handle);
+        }
+        let (commands, receiver) = mpsc::channel(128);
+        let output = Arc::new(OutputHub::default());
+        let cancellation = CancellationToken::new();
+        let handle = CursorSessionHandle {
+            request_id: request_id.into(),
+            commands,
+            output,
+            cancellation,
+            parent: Arc::new(OnceLock::new()),
+        };
+        let mut runs = self.inner.runs.lock().await;
+        if let Some(existing) = runs.get(request_id).cloned() {
+            return Ok(existing);
+        }
+        runs.insert(request_id.into(), handle.clone());
+        drop(runs);
+        let blob_sync =
+            BlobSynchronizer::new(request_id.into(), self.inner.store.clone(), handle.clone());
+        CursorActor::spawn(
+            handle.clone(),
+            receiver,
+            RunDependencies {
+                store: self.inner.store.clone(),
+                provider: self.inner.provider.clone(),
+                compiler: self.inner.compiler.clone(),
+                run_registry: self.inner.run_registry.clone(),
+            },
+            blob_sync,
+            0,
+        );
+        let registry = Arc::downgrade(&self.inner);
+        let request_id = request_id.to_string();
+        let output = handle.output.clone();
+        tokio::spawn(async move {
+            output.wait_closed().await;
+            let Some(registry) = registry.upgrade() else {
+                return;
+            };
+            registry.runs.lock().await.remove(&request_id);
+        });
+        Ok(handle)
+    }
+
+    pub async fn shutdown(&self) {
+        let handles = {
+            let mut runs = self.inner.runs.lock().await;
+            runs.drain().map(|(_, handle)| handle).collect::<Vec<_>>()
+        };
+        self.inner.run_registry.shutdown().await;
+        for handle in handles {
+            handle.cancel();
+            let _ = crate::cursor::lifecycle::cancel(&handle);
+        }
+    }
+}

cursor-server/src/cursor/tools.rs

@@ -1,318 +0,0 @@
-use std::collections::{BTreeMap, HashSet};
-
-use crate::{
-    model::{CanonicalMessage, MessageContent, Origin, Role, ToolCall},
-    Error, Result,
-};
-
-use super::{
-    exec, interaction,
-    pending::{ExecContext, PendingClientTools, PendingExecRegistry},
-    proto::agent::v1 as pb,
-    tool_result::{self, ToolCompletion},
-};
-
-#[derive(Clone)]
-pub struct ToolDispatcher {
-    pending_execs: PendingExecRegistry,
-    pending_interactions: PendingClientTools,
-}
-
-pub struct DispatchedTool {
-    pub messages: Vec<pb::AgentServerMessage>,
-    pub completion: Option<ToolCompletion>,
-}
-
-pub enum ClientToolEvent {
-    Message(Box<pb::AgentServerMessage>),
-    Completed(Box<ToolCompletion>),
-}
-
-impl ToolDispatcher {
-    pub fn new(
-        pending_execs: PendingExecRegistry,
-        pending_interactions: PendingClientTools,
-    ) -> Self {
-        Self {
-            pending_execs,
-            pending_interactions,
-        }
-    }
-
-    pub async fn start_batch(
-        &self,
-        calls: &[ToolCall],
-        completed: &HashSet<String>,
-        messages: &[CanonicalMessage],
-        response_text: &str,
-        response_thinking: &str,
-        dynamic_mcp: &BTreeMap<String, pb::McpToolDefinition>,
-        context: &ExecContext,
-    ) -> Result<Vec<DispatchedTool>> {
-        let first_tool_index = current_turn_step_count(messages)
-            + usize::from(!response_thinking.is_empty())
-            + usize::from(!response_text.is_empty())
-            + 1;
-        let mut dispatched = Vec::with_capacity(calls.len() - completed.len().min(calls.len()));
-        for (position, call) in calls.iter().enumerate() {
-            if completed.contains(&call.call_id) {
-                continue;
-            }
-            dispatched.push(
-                self.start(call, first_tool_index + position, dynamic_mcp, context)
-                    .await?,
-            );
-        }
-        Ok(dispatched)
-    }
-
-    async fn start(
-        &self,
-        call: &ToolCall,
-        message_index: usize,
-        dynamic_mcp: &BTreeMap<String, pb::McpToolDefinition>,
-        context: &ExecContext,
-    ) -> Result<DispatchedTool> {
-        let mut messages = vec![interaction::tool_started(call)?];
-        let completion = if let Some(definition) = dynamic_mcp.get(&call.name) {
-            let id = self.pending_execs.reserve(call, context).await?;
-            messages.push(exec::mcp_request(id, call, definition)?);
-            None
-        } else {
-            match normalized(&call.name).as_str() {
-                "shell"
-                | "forcebackgroundshell"
-                | "read"
-                | "write"
-                | "delete"
-                | "grep"
-                | "glob"
-                | "ls"
-                | "readlints"
-                | "patchedit"
-                | "writeshellstdin"
-                | "task"
-                | "callmcptool"
-                | "fetchmcpresource" => {
-                    let id = self.pending_execs.reserve(call, context).await?;
-                    messages.push(exec::request(id, call, context)?);
-                    None
-                }
-                "askquestion" | "websearch" | "webfetch" | "switchmode" | "createplan"
-                | "generateimage" => {
-                    let id = self.pending_interactions.reserve(call, context).await?;
-                    messages.push(interaction::tool_query(id, call)?);
-                    None
-                }
-                "todowrite" | "communicateupdate" => Some(tool_result::local(call, message_index)?),
-                _ => return Err(Error::Protocol(format!("unsupported tool: {}", call.name))),
-            }
-        };
-        Ok(DispatchedTool {
-            messages,
-            completion,
-        })
-    }
-
-    pub async fn interaction_response(
-        &self,
-        response: &pb::InteractionResponse,
-    ) -> Result<ClientToolEvent> {
-        let pending = self
-            .pending_interactions
-            .take(response.id)
-            .await
-            .ok_or_else(|| {
-                Error::Protocol(format!("unknown InteractionResponse id: {}", response.id))
-            })?;
-        if normalized(&pending.call.name) == "webfetch"
-            && matches!(
-                response.result.as_ref(),
-                Some(pb::interaction_response::Result::WebFetchRequestResponse(
-                    pb::WebFetchRequestResponse {
-                        result: Some(pb::web_fetch_request_response::Result::Approved(_)),
-                    }
-                ))
-            )
-        {
-            let id = self
-                .pending_execs
-                .reserve(&pending.call, &pending.context)
-                .await?;
-            return Ok(ClientToolEvent::Message(Box::new(exec::request(
-                id,
-                &pending.call,
-                &pending.context,
-            )?)));
-        }
-        Ok(ClientToolEvent::Completed(Box::new(
-            tool_result::from_interaction(pending, response)?,
-        )))
-    }
-}
-
-fn current_turn_step_count(messages: &[CanonicalMessage]) -> usize {
-    let turn_start = messages
-        .iter()
-        .rposition(|message| message.role == Role::User && message.origin == Origin::User)
-        .map_or(0, |position| position + 1);
-    messages[turn_start..]
-        .iter()
-        .map(|message| match &message.content {
-            MessageContent::Assistant {
-                text,
-                thinking,
-                tool_calls,
-                ..
-            } => {
-                usize::from(!thinking.is_empty()) + usize::from(!text.is_empty()) + tool_calls.len()
-            }
-            _ => 0,
-        })
-        .sum()
-}
-
-fn normalized(name: &str) -> String {
-    name.chars()
-        .filter(|character| character.is_ascii_alphanumeric())
-        .flat_map(char::to_lowercase)
-        .collect()
-}
-
-#[cfg(test)]
-mod tests {
-    use serde_json::json;
-
-    use super::*;
-    use crate::model::{CanonicalMessage, Origin, Role};
-
-    fn call(name: &str) -> ToolCall {
-        ToolCall {
-            index: 0,
-            call_id: "call-1".into(),
-            model_call_id: "model-1".into(),
-            name: name.into(),
-            arguments_text: "{}".into(),
-            arguments: json!({}),
-        }
-    }
-
-    #[tokio::test]
-    async fn communicate_update_completes_locally_at_the_cursor_step_index() {
-        let dispatcher = ToolDispatcher::new(
-            PendingExecRegistry::default(),
-            PendingClientTools::default(),
-        );
-        let calls = [ToolCall {
-            arguments: json!({"current_step": "Reading"}),
-            ..call("CommunicateUpdate")
-        }];
-        let user = CanonicalMessage::text("user", Role::User, Origin::User, "go");
-        let dispatched = dispatcher
-            .start_batch(
-                &calls,
-                &HashSet::new(),
-                &[user],
-                "I will inspect it.",
-                "Need to read.",
-                &BTreeMap::new(),
-                &ExecContext::default(),
-            )
-            .await
-            .unwrap();
-        let completion = dispatched[0].completion.as_ref().unwrap();
-        let Some(pb::tool_call::Tool::CommunicateUpdateToolCall(tool)) =
-            completion.tool_call().tool.as_ref()
-        else {
-            panic!("expected CommunicateUpdateToolCall")
-        };
-        let Some(pb::communicate_update_result::Result::Success(success)) = tool
-            .result
-            .as_ref()
-            .and_then(|result| result.result.as_ref())
-        else {
-            panic!("expected communicate update success")
-        };
-        assert_eq!(success.message_index, 3);
-    }
-
-    #[tokio::test]
-    async fn approved_web_fetch_moves_from_interaction_to_exec() {
-        let dispatcher = ToolDispatcher::new(
-            PendingExecRegistry::default(),
-            PendingClientTools::default(),
-        );
-        let calls = [ToolCall {
-            arguments: json!({"url": "https://example.com"}),
-            ..call("WebFetch")
-        }];
-        let dispatched = dispatcher
-            .start_batch(
-                &calls,
-                &HashSet::new(),
-                &[],
-                "",
-                "",
-                &BTreeMap::new(),
-                &ExecContext::default(),
-            )
-            .await
-            .unwrap();
-        let Some(pb::agent_server_message::Message::InteractionQuery(query)) =
-            dispatched[0].messages[1].message.as_ref()
-        else {
-            panic!("expected WebFetch InteractionQuery")
-        };
-        let event = dispatcher
-            .interaction_response(&pb::InteractionResponse {
-                id: query.id,
-                result: Some(pb::interaction_response::Result::WebFetchRequestResponse(
-                    pb::WebFetchRequestResponse {
-                        result: Some(pb::web_fetch_request_response::Result::Approved(
-                            pb::web_fetch_request_response::Approved {},
-                        )),
-                    },
-                )),
-            })
-            .await
-            .unwrap();
-        let ClientToolEvent::Message(message) = event else {
-            panic!("approval must open the Exec phase")
-        };
-        let Some(pb::agent_server_message::Message::ExecServerMessage(exec)) = message.message
-        else {
-            panic!("expected FetchArgs")
-        };
-        assert!(matches!(
-            exec.message,
-            Some(pb::exec_server_message::Message::FetchArgs(_))
-        ));
-        let event = exec::client_event(
-            &pb::ExecClientMessage {
-                id: exec.id,
-                message: Some(pb::exec_client_message::Message::FetchResult(
-                    pb::FetchResult {
-                        result: Some(pb::fetch_result::Result::Success(pb::FetchSuccess {
-                            url: "https://example.com".into(),
-                            content: "hello".into(),
-                            status_code: 200,
-                            content_type: "text/html".into(),
-                        })),
-                    },
-                )),
-                ..Default::default()
-            },
-            &dispatcher.pending_execs,
-        )
-        .await
-        .unwrap();
-        let exec::ClientExecEvent::Completed(completion) = event else {
-            panic!("FetchResult must complete WebFetch")
-        };
-        assert_eq!(completion.result().output, json!("hello"));
-        assert!(matches!(
-            completion.tool_call().tool,
-            Some(pb::tool_call::Tool::WebFetchToolCall(_))
-        ));
-    }
-}

cursor-server/src/cursor/tools/codec/mod.rs

@@ -0,0 +1,8 @@
+mod request;
+mod response;
+
+pub use request::{abort, mcp_request, mcp_state_request, request};
+pub(crate) use request::{
+    await_read_request, edit_read_request, json_object_to_prost, mcp_meta_request,
+};
+pub use response::{client_event, ClientExecEvent};

cursor-server/src/cursor/tools/codec/request.rs

@@ -0,0 +1,520 @@
+use serde_json::{Map, Value};
+
+use crate::{
+    cursor::{
+        proto::agent::v1 as pb,
+        tools::{
+            edit::{self, EditWrite},
+            runtime::{ExecContext, SubagentModel},
+        },
+    },
+    model::ToolCall,
+    Error, Result,
+};
+
+pub fn request(id: u32, call: &ToolCall, context: &ExecContext) -> Result<pb::AgentServerMessage> {
+    use pb::exec_server_message::Message;
+    let string = |name: &str| {
+        call.arguments
+            .get(name)
+            .and_then(Value::as_str)
+            .map(str::to_string)
+            .ok_or_else(|| Error::Protocol(format!("{} is missing {name}", call.name)))
+    };
+    let optional_string = |name: &str| {
+        call.arguments
+            .get(name)
+            .and_then(Value::as_str)
+            .map(str::to_string)
+    };
+    let int = |name: &str| {
+        call.arguments
+            .get(name)
+            .and_then(Value::as_i64)
+            .map(|v| v as i32)
+    };
+    let message = match normalize(&call.name).as_str() {
+        "shell" => Message::ShellStreamArgs(pb::ShellArgs {
+            command: string("command")?,
+            working_directory: optional_string("working_directory").unwrap_or_default(),
+            timeout: shell_timeout(call)?,
+            tool_call_id: call.call_id.clone(),
+            file_output_threshold_bytes: Some(40_000),
+            timeout_behavior: pb::TimeoutBehavior::Background as i32,
+            hard_timeout: Some(86_400_000),
+            description: optional_string("description"),
+            output_notification: shell_notification(call)?,
+            smart_mode_approval: smart_mode_approval(
+                call,
+                "request_smart_mode_approval",
+                "smart_mode_block_reason",
+            )?,
+            close_stdin: true,
+            conversation_id: Some(context.conversation_id.clone()),
+            admin_command_denylist: context.admin_command_denylist.clone(),
+            ..Default::default()
+        }),
+        "read" => Message::ReadArgs(pb::ReadArgs {
+            path: string("path")?,
+            tool_call_id: call.call_id.clone(),
+            offset: int("offset"),
+            limit: call
+                .arguments
+                .get("limit")
+                .and_then(Value::as_u64)
+                .map(|v| v as u32),
+            encoding_hint: optional_string("encoding_hint"),
+        }),
+        "delete" => Message::DeleteArgs(pb::DeleteArgs {
+            path: string("path")?,
+            tool_call_id: call.call_id.clone(),
+        }),
+        "grep" => Message::GrepArgs(pb::GrepArgs {
+            pattern: string("pattern")?,
+            path: optional_string("path"),
+            glob: optional_string("glob"),
+            output_mode: optional_string("output_mode"),
+            context_before: int("-B"),
+            context_after: int("-A"),
+            context: int("-C"),
+            case_insensitive: call.arguments.get("-i").and_then(Value::as_bool),
+            r#type: optional_string("type"),
+            head_limit: int("head_limit"),
+            multiline: call.arguments.get("multiline").and_then(Value::as_bool),
+            sort: optional_string("sort"),
+            sort_ascending: call
+                .arguments
+                .get("sort_ascending")
+                .and_then(Value::as_bool),
+            tool_call_id: call.call_id.clone(),
+            sandbox_policy: None,
+            offset: int("offset"),
+        }),
+        "glob" => Message::GrepArgs(pb::GrepArgs {
+            pattern: String::new(),
+            path: optional_string("target_directory"),
+            glob: optional_string("glob_pattern"),
+            output_mode: Some("files_with_matches".into()),
+            tool_call_id: call.call_id.clone(),
+            ..Default::default()
+        }),
+        "readlints" => Message::DiagnosticsArgs(pb::DiagnosticsArgs {
+            path: call
+                .arguments
+                .get("paths")
+                .and_then(Value::as_array)
+                .and_then(|paths| paths.first())
+                .and_then(Value::as_str)
+                .unwrap_or_default()
+                .into(),
+            tool_call_id: call.call_id.clone(),
+        }),
+        "task" => Message::SubagentArgs(pb::SubagentArgs {
+            tool_call_id: call.call_id.clone(),
+            subagent_type: optional_string("subagent_type").unwrap_or_default(),
+            model_id: task_model(call, context)?,
+            prompt: string("prompt")?,
+            readonly: false,
+            resume_agent_id: optional_string("resume"),
+            run_in_background: call
+                .arguments
+                .get("run_in_background")
+                .and_then(Value::as_bool),
+            continuation_config: None,
+            parent_conversation_id: Some(context.conversation_id.clone()),
+            interrupt: call.arguments.get("interrupt").and_then(Value::as_bool),
+            mode: 0,
+            fork_agent_id: None,
+            root_parent_conversation_id: Some(context.root_conversation_id.clone()),
+            selected_context: task_attachments(call),
+            direct_meta_parent_child_subagent: None,
+            environment: match optional_string("environment").as_deref() {
+                Some("cloud") => pb::SubagentExecutionEnvironment::Cloud as i32,
+                Some("local") | None => pb::SubagentExecutionEnvironment::Local as i32,
+                Some(value) => {
+                    return Err(Error::Protocol(format!(
+                        "unknown Task environment: {value}"
+                    )))
+                }
+            },
+            cloud_base_branch: optional_string("cloud_base_branch"),
+            credentials: None,
+        }),
+        "fetchmcpresource" => Message::ReadMcpResourceExecArgs(pb::ReadMcpResourceExecArgs {
+            server: string("server")?,
+            uri: string("uri")?,
+            download_path: optional_string("downloadPath"),
+            tool_call_id: call.call_id.clone(),
+            smart_mode_approval: smart_mode_approval(
+                call,
+                "requestSmartModeApproval",
+                "smartModeBlockReason",
+            )?,
+        }),
+        "webfetch" => Message::FetchArgs(pb::FetchArgs {
+            url: string("url")?,
+            tool_call_id: call.call_id.clone(),
+        }),
+        other => {
+            return Err(Error::Protocol(format!(
+                "tool {other} is not executed through ExecServerMessage"
+            )))
+        }
+    };
+    let accept_hook_additional_contexts =
+        if matches!(&message, pb::exec_server_message::Message::SubagentArgs(_)) {
+            Some(false)
+        } else {
+            Some(true)
+        };
+    Ok(server_message(
+        id,
+        call,
+        message,
+        accept_hook_additional_contexts,
+    ))
+}
+
+pub(crate) fn edit_read_request(id: u32, call: &ToolCall) -> Result<pb::AgentServerMessage> {
+    Ok(server_message(
+        id,
+        call,
+        pb::exec_server_message::Message::ReadArgs(pb::ReadArgs {
+            path: edit::path(call)?,
+            tool_call_id: call.call_id.clone(),
+            ..Default::default()
+        }),
+        Some(true),
+    ))
+}
+
+pub(crate) fn await_read_request(
+    id: u32,
+    call: &ToolCall,
+    context: &ExecContext,
+) -> Result<pb::AgentServerMessage> {
+    let task_id = call
+        .arguments
+        .get("shell_id")
+        .and_then(Value::as_str)
+        .ok_or_else(|| Error::Protocol("AwaitShell is missing shell_id".into()))?;
+    Ok(server_message(
+        id,
+        call,
+        pb::exec_server_message::Message::ReadArgs(pb::ReadArgs {
+            path: format!(
+                "{}/{}.txt",
+                context.terminals_folder.trim_end_matches('/'),
+                task_id
+            ),
+            tool_call_id: call.call_id.clone(),
+            ..Default::default()
+        }),
+        Some(false),
+    ))
+}
+
+pub(super) fn edit_write_request(
+    id: u32,
+    call: &ToolCall,
+    write: &EditWrite,
+) -> Result<pb::AgentServerMessage> {
+    Ok(server_message(
+        id,
+        call,
+        pb::exec_server_message::Message::WriteArgs(pb::WriteArgs {
+            path: edit::path(call)?,
+            file_text: write.after.clone(),
+            tool_call_id: call.call_id.clone(),
+            return_file_content_after_write: false,
+            file_bytes: Vec::new(),
+            encoding_hint: None,
+        }),
+        Some(true),
+    ))
+}
+
+fn server_message(
+    id: u32,
+    call: &ToolCall,
+    message: pb::exec_server_message::Message,
+    accept_hook_additional_contexts: Option<bool>,
+) -> pb::AgentServerMessage {
+    pb::AgentServerMessage {
+        ttft_breakdown: None,
+        message: Some(pb::agent_server_message::Message::ExecServerMessage(
+            pb::ExecServerMessage {
+                id,
+                exec_id: call.call_id.clone(),
+                span_context: None,
+                accept_hook_additional_contexts,
+                message: Some(message),
+            },
+        )),
+    }
+}
+
+pub fn mcp_request(
+    id: u32,
+    call: &ToolCall,
+    definition: &pb::McpToolDefinition,
+) -> Result<pb::AgentServerMessage> {
+    let args = call
+        .arguments
+        .as_object()
+        .map(json_object_to_prost)
+        .unwrap_or_default();
+    Ok(pb::AgentServerMessage {
+        ttft_breakdown: None,
+        message: Some(pb::agent_server_message::Message::ExecServerMessage(
+            pb::ExecServerMessage {
+                id,
+                exec_id: call.call_id.clone(),
+                span_context: None,
+                accept_hook_additional_contexts: None,
+                message: Some(pb::exec_server_message::Message::McpArgs(pb::McpArgs {
+                    name: definition.name.clone(),
+                    args,
+                    tool_call_id: call.call_id.clone(),
+                    provider_identifier: definition.provider_identifier.clone(),
+                    tool_name: definition.tool_name.clone(),
+                    smart_mode_approval: None,
+                    smart_mode_approval_only: false,
+                    skip_approval: false,
+                    server_identifier: String::new(),
+                })),
+            },
+        )),
+    })
+}
+
+pub(crate) fn mcp_meta_request(
+    id: u32,
+    call: &ToolCall,
+    server_identifier: &str,
+    definition: &pb::McpToolDefinition,
+) -> Result<pb::AgentServerMessage> {
+    if definition.name.is_empty()
+        || definition.provider_identifier.is_empty()
+        || definition.tool_name.is_empty()
+    {
+        return Err(Error::Protocol(format!(
+            "MCP definition for {server_identifier} is incomplete"
+        )));
+    }
+    let requested_tool = call
+        .arguments
+        .get("toolName")
+        .and_then(Value::as_str)
+        .ok_or_else(|| Error::Protocol("CallMcpTool is missing toolName".into()))?;
+    if requested_tool != definition.tool_name {
+        return Err(Error::Protocol(format!(
+            "MCP definition mismatch: requested {requested_tool}, resolved {}",
+            definition.tool_name
+        )));
+    }
+    let args = call
+        .arguments
+        .get("arguments")
+        .and_then(Value::as_object)
+        .map(json_object_to_prost)
+        .unwrap_or_default();
+    Ok(server_message(
+        id,
+        call,
+        pb::exec_server_message::Message::McpArgs(pb::McpArgs {
+            name: definition.name.clone(),
+            args,
+            tool_call_id: call.call_id.clone(),
+            provider_identifier: definition.provider_identifier.clone(),
+            tool_name: definition.tool_name.clone(),
+            smart_mode_approval: smart_mode_approval(
+                call,
+                "requestSmartModeApproval",
+                "smartModeBlockReason",
+            )?,
+            smart_mode_approval_only: false,
+            skip_approval: false,
+            server_identifier: server_identifier.into(),
+        }),
+        Some(true),
+    ))
+}
+
+pub fn mcp_state_request(id: u32, call: &ToolCall) -> pb::AgentServerMessage {
+    let server_identifiers = call
+        .arguments
+        .get("server")
+        .and_then(Value::as_str)
+        .map(|server| vec![server.into()])
+        .unwrap_or_default();
+    server_message(
+        id,
+        call,
+        pb::exec_server_message::Message::McpStateExecArgs(pb::McpStateExecArgs {
+            server_identifiers,
+            kick_only: false,
+        }),
+        Some(false),
+    )
+}
+
+pub fn abort(id: u32) -> pb::AgentServerMessage {
+    pb::AgentServerMessage {
+        ttft_breakdown: None,
+        message: Some(pb::agent_server_message::Message::ExecServerControlMessage(
+            pb::ExecServerControlMessage {
+                message: Some(pb::exec_server_control_message::Message::Abort(
+                    pb::ExecServerAbort { id },
+                )),
+            },
+        )),
+    }
+}
+
+fn shell_timeout(call: &ToolCall) -> Result<i32> {
+    let value = call
+        .arguments
+        .get("block_until_ms")
+        .map(|value| {
+            value
+                .as_i64()
+                .ok_or_else(|| Error::Protocol("Shell block_until_ms must be an integer".into()))
+        })
+        .transpose()?
+        .unwrap_or(30_000);
+    i32::try_from(value)
+        .ok()
+        .filter(|value| *value >= 0)
+        .ok_or_else(|| Error::Protocol("Shell block_until_ms is out of range".into()))
+}
+
+fn smart_mode_approval(
+    call: &ToolCall,
+    request_field: &str,
+    reason_field: &str,
+) -> Result<Option<pb::SmartModeApproval>> {
+    if !call
+        .arguments
+        .get(request_field)
+        .and_then(Value::as_bool)
+        .unwrap_or(false)
+    {
+        return Ok(None);
+    }
+    let reason = call
+        .arguments
+        .get(reason_field)
+        .and_then(Value::as_str)
+        .ok_or_else(|| Error::Protocol(format!("{} requires {reason_field}", call.name)))?;
+    Ok(Some(pb::SmartModeApproval {
+        request_id: call.call_id.clone(),
+        reason: reason.to_string(),
+    }))
+}
+
+fn shell_notification(call: &ToolCall) -> Result<Option<pb::ShellOutputNotificationConfig>> {
+    let Some(value) = call.arguments.get("notify_on_output") else {
+        return Ok(None);
+    };
+    let object = value
+        .as_object()
+        .ok_or_else(|| Error::Protocol("Shell notify_on_output must be an object".into()))?;
+    let required = |field: &str| {
+        object
+            .get(field)
+            .and_then(Value::as_str)
+            .map(str::to_string)
+            .ok_or_else(|| Error::Protocol(format!("Shell notify_on_output is missing {field}")))
+    };
+    Ok(Some(pb::ShellOutputNotificationConfig {
+        pattern: required("pattern")?,
+        reason: required("reason")?,
+        debounce: object.get("debounce_ms").and_then(Value::as_f64),
+        notification_limit: None,
+    }))
+}
+
+fn task_attachments(call: &ToolCall) -> Option<pb::SelectedContext> {
+    let paths = call.arguments.get("file_attachments")?.as_array()?;
+    let mut context = pb::SelectedContext::default();
+    for path in paths.iter().filter_map(Value::as_str) {
+        let extension = std::path::Path::new(path)
+            .extension()
+            .and_then(std::ffi::OsStr::to_str)
+            .unwrap_or_default()
+            .to_ascii_lowercase();
+        if matches!(extension.as_str(), "mp4" | "mov" | "webm" | "mkv") {
+            context.selected_videos.push(pb::SelectedVideo {
+                path: path.into(),
+                filename: std::path::Path::new(path)
+                    .file_name()
+                    .and_then(std::ffi::OsStr::to_str)
+                    .unwrap_or_default()
+                    .into(),
+                materialize_to_filesystem: true,
+                ..Default::default()
+            });
+        } else {
+            context.selected_images.push(pb::SelectedImage {
+                path: path.into(),
+                ..Default::default()
+            });
+        }
+    }
+    Some(context)
+}
+
+fn task_model(call: &ToolCall, context: &ExecContext) -> Result<String> {
+    let subagent_type = call
+        .arguments
+        .get("subagent_type")
+        .and_then(Value::as_str)
+        .unwrap_or("generalPurpose");
+    if let Some(selection) = context.subagent_models.get(subagent_type) {
+        return match selection {
+            SubagentModel::Model(model) => Ok(model.clone()),
+            SubagentModel::Disabled => Err(Error::Protocol(format!(
+                "Task subagent type {subagent_type} is disabled"
+            ))),
+        };
+    }
+    match call.arguments.get("model").and_then(Value::as_str) {
+        None | Some("inherit") => Ok(context.model_id.clone()),
+        Some(model) => Ok(model.into()),
+    }
+}
+
+fn normalize(value: &str) -> String {
+    value
+        .chars()
+        .filter(|c| c.is_ascii_alphanumeric())
+        .flat_map(char::to_lowercase)
+        .collect()
+}
+
+pub(crate) fn json_object_to_prost(
+    value: &Map<String, Value>,
+) -> std::collections::HashMap<String, prost_types::Value> {
+    value
+        .iter()
+        .map(|(key, value)| (key.clone(), prost_value(value)))
+        .collect()
+}
+
+fn prost_value(value: &Value) -> prost_types::Value {
+    use prost_types::{value::Kind, ListValue, Struct, Value as ProstValue};
+    let kind = match value {
+        Value::Null => Kind::NullValue(0),
+        Value::Bool(v) => Kind::BoolValue(*v),
+        Value::Number(v) => Kind::NumberValue(v.as_f64().unwrap_or_default()),
+        Value::String(v) => Kind::StringValue(v.clone()),
+        Value::Array(v) => Kind::ListValue(ListValue {
+            values: v.iter().map(prost_value).collect(),
+        }),
+        Value::Object(v) => Kind::StructValue(Struct {
+            fields: json_object_to_prost(v).into_iter().collect(),
+        }),
+    };
+    ProstValue { kind: Some(kind) }
+}

cursor-server/src/cursor/tools/codec/response.rs

@@ -0,0 +1,360 @@
+use crate::{
+    cursor::{
+        interaction,
+        proto::agent::v1 as pb,
+        tools::{
+            edit,
+            result::{self, ToolCompletion},
+            runtime::{CursorToolRuntime, ExecStage, PendingExec},
+        },
+    },
+    model::ToolCall,
+    Error, Result,
+};
+
+use super::request::{await_read_request, edit_write_request};
+
+pub enum ClientExecEvent {
+    Delta(Box<pb::AgentServerMessage>),
+    Message(Box<pb::AgentServerMessage>),
+    Completed(Box<ToolCompletion>),
+    Pending,
+}
+
+pub async fn client_event(
+    message: &pb::ExecClientMessage,
+    pending: &CursorToolRuntime,
+) -> Result<ClientExecEvent> {
+    let call = match pending.exec_call(message.id).await {
+        Some(call) => call,
+        None if pending.completed_call(message.id).await.is_some() => {
+            return Err(Error::Protocol(format!(
+                "duplicate terminal ExecClientMessage id: {}",
+                message.id
+            )))
+        }
+        None => {
+            return Err(Error::Protocol(format!(
+                "unknown ExecClientMessage id: {}",
+                message.id
+            )))
+        }
+    };
+    let Some(wire_result) = &message.message else {
+        return Ok(ClientExecEvent::Pending);
+    };
+    let pb::exec_client_message::Message::ShellStream(stream) = wire_result else {
+        let entry = take(message.id, pending).await?;
+        return match entry.stage {
+            ExecStage::EditRead => advance_edit(entry, wire_result, pending).await,
+            ExecStage::Await(_) => advance_await(entry, wire_result, pending).await,
+            ExecStage::Direct | ExecStage::EditWrite(_) => {
+                if let pb::exec_client_message::Message::McpStateExecResult(state) = wire_result {
+                    pending.remember_mcp_state(&entry.call, state).await;
+                }
+                completed(entry, wire_result.clone())
+            }
+        };
+    };
+    use pb::shell_stream::Event;
+    let event = match &stream.event {
+        Some(Event::Stdout(stdout)) => {
+            if pending.append_stdout(message.id, &stdout.data).await {
+                ClientExecEvent::Delta(Box::new(shell_delta(&call, true, &stdout.data)))
+            } else {
+                ClientExecEvent::Pending
+            }
+        }
+        Some(Event::Stderr(stderr)) => {
+            if pending.append_stderr(message.id, &stderr.data).await {
+                ClientExecEvent::Delta(Box::new(shell_delta(&call, false, &stderr.data)))
+            } else {
+                ClientExecEvent::Pending
+            }
+        }
+        Some(Event::Start(_)) | Some(Event::HookContext(_)) => ClientExecEvent::Pending,
+        Some(Event::Exit(exit)) => {
+            let entry = take(message.id, pending).await?;
+            let result = shell_exit_result(message, exit, &entry.stdout, &entry.stderr);
+            completed(entry, pb::exec_client_message::Message::ShellResult(result))?
+        }
+        Some(Event::Backgrounded(backgrounded)) => {
+            let entry = take(message.id, pending).await?;
+            let result = shell_backgrounded_result(
+                backgrounded,
+                &entry.stdout,
+                &entry.stderr,
+                &entry.context.terminals_folder,
+            );
+            completed(entry, pb::exec_client_message::Message::ShellResult(result))?
+        }
+        Some(Event::Rejected(value)) => {
+            let result = pb::ShellResult {
+                result: Some(pb::shell_result::Result::Rejected(value.clone())),
+                ..Default::default()
+            };
+            complete(
+                message.id,
+                pending,
+                pb::exec_client_message::Message::ShellResult(result),
+            )
+            .await?
+        }
+        Some(Event::PermissionDenied(value)) => {
+            let result = pb::ShellResult {
+                result: Some(pb::shell_result::Result::PermissionDenied(value.clone())),
+                ..Default::default()
+            };
+            complete(
+                message.id,
+                pending,
+                pb::exec_client_message::Message::ShellResult(result),
+            )
+            .await?
+        }
+        Some(Event::SandboxUnsupported(value)) => {
+            let result = pb::ShellResult {
+                result: Some(pb::shell_result::Result::SpawnError(pb::ShellSpawnError {
+                    command: value.command.clone(),
+                    working_directory: value.working_directory.clone(),
+                    error: value.reason.clone(),
+                })),
+                ..Default::default()
+            };
+            complete(
+                message.id,
+                pending,
+                pb::exec_client_message::Message::ShellResult(result),
+            )
+            .await?
+        }
+        None => ClientExecEvent::Pending,
+    };
+    Ok(event)
+}
+
+async fn advance_await(
+    entry: PendingExec,
+    result: &pb::exec_client_message::Message,
+    registry: &CursorToolRuntime,
+) -> Result<ClientExecEvent> {
+    let read = match result {
+        pb::exec_client_message::Message::ReadResult(result)
+        | pb::exec_client_message::Message::RedactedReadResult(result) => result,
+        _ => return Err(Error::Protocol("AwaitShell expected ReadResult".into())),
+    };
+    let ExecStage::Await(state) = &entry.stage else {
+        return Err(Error::Protocol(
+            "AwaitShell result reached a non-await execution stage".into(),
+        ));
+    };
+    let content = match read.result.as_ref() {
+        Some(pb::read_result::Result::Success(success)) => match success.output.as_ref() {
+            Some(pb::read_success::Output::Content(content)) => content.as_str(),
+            _ => "",
+        },
+        Some(pb::read_result::Result::FileNotFound(_)) => "",
+        Some(pb::read_result::Result::Error(error)) => {
+            return Ok(ClientExecEvent::Completed(Box::new(result::await_error(
+                entry,
+                &error.error,
+            )?)))
+        }
+        _ => "",
+    };
+    let regex_match = state
+        .regex
+        .as_ref()
+        .map(|pattern| regex::Regex::new(pattern))
+        .transpose()
+        .map_err(|error| Error::Protocol(format!("invalid AwaitShell pattern: {error}")))?
+        .and_then(|pattern| {
+            pattern
+                .find(content)
+                .map(|found| found.as_str().to_string())
+        });
+    let exit_code = content.lines().find_map(|line| {
+        line.strip_prefix("exit_code:")
+            .and_then(|value| value.trim().parse::<i32>().ok())
+    });
+    if regex_match.is_some() || exit_code.is_some() || std::time::Instant::now() >= state.deadline {
+        return Ok(ClientExecEvent::Completed(Box::new(result::await_result(
+            entry,
+            content.len() as u64,
+            regex_match,
+            exit_code,
+        )?)));
+    }
+    let state = match entry.stage {
+        ExecStage::Await(state) => state,
+        _ => {
+            return Err(Error::Protocol(
+                "AwaitShell result changed execution stage".into(),
+            ))
+        }
+    };
+    let wait = state
+        .deadline
+        .saturating_duration_since(std::time::Instant::now())
+        .min(std::time::Duration::from_secs(1));
+    tokio::time::sleep(wait).await;
+    let call = entry.call.clone();
+    let context = entry.context.clone();
+    let id = registry
+        .reserve_await_again(&call, &context, state, entry.started_at_ms)
+        .await?;
+    Ok(ClientExecEvent::Message(Box::new(await_read_request(
+        id, &call, &context,
+    )?)))
+}
+
+async fn advance_edit(
+    entry: PendingExec,
+    result: &pb::exec_client_message::Message,
+    registry: &CursorToolRuntime,
+) -> Result<ClientExecEvent> {
+    let read = match result {
+        pb::exec_client_message::Message::ReadResult(result)
+        | pb::exec_client_message::Message::RedactedReadResult(result) => result,
+        _ => {
+            return Err(Error::Protocol(format!(
+                "expected ReadResult for edit tool {}",
+                entry.call.name
+            )))
+        }
+    };
+    let write = match edit::after_read(&entry.call, read) {
+        Ok(write) => write,
+        Err(error) => {
+            return Ok(ClientExecEvent::Completed(Box::new(result::edit_failure(
+                entry, error,
+            )?)))
+        }
+    };
+    let id = registry
+        .reserve_edit_write(
+            &entry.call,
+            &entry.context,
+            write.clone(),
+            entry.started_at_ms,
+        )
+        .await?;
+    Ok(ClientExecEvent::Message(Box::new(edit_write_request(
+        id,
+        &entry.call,
+        &write,
+    )?)))
+}
+
+async fn complete(
+    id: u32,
+    pending: &CursorToolRuntime,
+    result: pb::exec_client_message::Message,
+) -> Result<ClientExecEvent> {
+    completed(take(id, pending).await?, result)
+}
+
+async fn take(id: u32, pending: &CursorToolRuntime) -> Result<PendingExec> {
+    pending
+        .take_exec(id)
+        .await
+        .ok_or_else(|| Error::Protocol(format!("unknown terminal Exec id: {id}")))
+}
+
+fn completed(
+    pending: PendingExec,
+    result: pb::exec_client_message::Message,
+) -> Result<ClientExecEvent> {
+    Ok(ClientExecEvent::Completed(Box::new(result::from_exec(
+        pending, &result,
+    )?)))
+}
+
+fn shell_exit_result(
+    message: &pb::ExecClientMessage,
+    exit: &pb::ShellStreamExit,
+    stdout: &str,
+    stderr: &str,
+) -> pb::ShellResult {
+    let result = if exit.code == 0 && !exit.aborted {
+        pb::shell_result::Result::Success(pb::ShellSuccess {
+            working_directory: exit.cwd.clone(),
+            exit_code: exit.code as i32,
+            stdout: stdout.into(),
+            stderr: stderr.into(),
+            interleaved_output: Some(format!("{stdout}{stderr}")),
+            local_execution_time_ms: exit
+                .local_execution_time_ms
+                .or(message.local_execution_time_ms),
+            ..Default::default()
+        })
+    } else {
+        pb::shell_result::Result::Failure(pb::ShellFailure {
+            working_directory: exit.cwd.clone(),
+            exit_code: exit.code as i32,
+            stdout: stdout.into(),
+            stderr: stderr.into(),
+            interleaved_output: Some(format!("{stdout}{stderr}")),
+            abort_reason: exit.abort_reason,
+            aborted: exit.aborted,
+            local_execution_time_ms: exit
+                .local_execution_time_ms
+                .or(message.local_execution_time_ms),
+            ..Default::default()
+        })
+    };
+    pb::ShellResult {
+        result: Some(result),
+        is_background: Some(false),
+        ..Default::default()
+    }
+}
+
+fn shell_backgrounded_result(
+    backgrounded: &pb::ShellStreamBackgrounded,
+    stdout: &str,
+    stderr: &str,
+    terminals_folder: &str,
+) -> pb::ShellResult {
+    pb::ShellResult {
+        result: Some(pb::shell_result::Result::Success(pb::ShellSuccess {
+            command: backgrounded.command.clone(),
+            working_directory: backgrounded.working_directory.clone(),
+            stdout: stdout.into(),
+            stderr: stderr.into(),
+            shell_id: Some(backgrounded.shell_id),
+            pid: backgrounded.pid,
+            ms_to_wait: backgrounded.ms_to_wait,
+            background_reason: backgrounded.reason,
+            interleaved_output: Some(format!("{stdout}{stderr}")),
+            ..Default::default()
+        })),
+        is_background: Some(true),
+        terminals_folder: (!terminals_folder.is_empty()).then(|| terminals_folder.into()),
+        pid: backgrounded.pid,
+        ..Default::default()
+    }
+}
+
+fn shell_delta(call: &ToolCall, stdout: bool, content: &str) -> pb::AgentServerMessage {
+    let delta = if stdout {
+        pb::shell_tool_call_delta::Delta::Stdout(pb::ShellToolCallStdoutDelta {
+            content: content.into(),
+        })
+    } else {
+        pb::shell_tool_call_delta::Delta::Stderr(pb::ShellToolCallStderrDelta {
+            content: content.into(),
+        })
+    };
+    interaction::server_interaction(pb::interaction_update::Message::ToolCallDelta(Box::new(
+        pb::ToolCallDeltaUpdate {
+            call_id: call.call_id.clone(),
+            tool_call_delta: Some(Box::new(pb::ToolCallDelta {
+                delta: Some(pb::tool_call_delta::Delta::ShellToolCallDelta(
+                    pb::ShellToolCallDelta { delta: Some(delta) },
+                )),
+            })),
+            model_call_id: call.model_call_id.clone(),
+        },
+    )))
+}

cursor-server/src/cursor/tools/dispatch/await_shell.rs

@@ -0,0 +1,54 @@
+//! AwaitShell's timed and file-backed execution paths.
+
+use crate::{model::ToolCall, Error, Result};
+
+use super::ToolStart;
+use crate::cursor::tools::{
+    codec, result,
+    result::ToolResultSender,
+    runtime::{CursorToolRuntime, ExecContext},
+};
+
+pub(super) async fn start(
+    runtime: &CursorToolRuntime,
+    results: &ToolResultSender,
+    call: &ToolCall,
+    context: &ExecContext,
+) -> Result<ToolStart> {
+    let message = if call
+        .arguments
+        .get("shell_id")
+        .and_then(serde_json::Value::as_str)
+        .is_some()
+    {
+        let id = runtime.reserve_await(call, context).await?;
+        Some(codec::await_read_request(id, call, context)?)
+    } else {
+        wait_without_shell_id(results, call)?;
+        None
+    };
+    Ok(ToolStart {
+        messages: message.into_iter().collect(),
+        completion: None,
+    })
+}
+
+fn wait_without_shell_id(results: &ToolResultSender, call: &ToolCall) -> Result<()> {
+    let block_ms = call
+        .arguments
+        .get("block_until_ms")
+        .and_then(serde_json::Value::as_u64)
+        .unwrap_or(30_000);
+    if block_ms == 0 || block_ms > 7_140_000 {
+        return Err(Error::Protocol(
+            "AwaitShell without shell_id requires block_until_ms in 1..=7140000".into(),
+        ));
+    }
+    let call = call.clone();
+    let results = results.clone();
+    tokio::spawn(async move {
+        tokio::time::sleep(std::time::Duration::from_millis(block_ms)).await;
+        results.send(result::await_sleep(&call, block_ms));
+    });
+    Ok(())
+}

cursor-server/src/cursor/tools/dispatch/edit.rs

@@ -0,0 +1,21 @@
+//! Hidden read phase for file editing tools.
+
+use crate::{model::ToolCall, Result};
+
+use super::ToolStart;
+use crate::cursor::tools::{
+    codec,
+    runtime::{CursorToolRuntime, ExecContext},
+};
+
+pub(super) async fn start(
+    runtime: &CursorToolRuntime,
+    call: &ToolCall,
+    context: &ExecContext,
+) -> Result<ToolStart> {
+    let id = runtime.reserve_edit_read(call, context).await?;
+    Ok(ToolStart {
+        messages: vec![codec::edit_read_request(id, call)?],
+        completion: None,
+    })
+}

cursor-server/src/cursor/tools/dispatch/exec.rs

@@ -0,0 +1,62 @@
+//! Direct Exec and dynamic MCP dispatch.
+
+use crate::{cursor::proto::agent::v1 as pb, model::ToolCall, Error, Result};
+
+use super::{normalized, ToolStart};
+use crate::cursor::tools::{
+    codec,
+    runtime::{CursorToolRuntime, ExecContext},
+};
+
+pub(super) async fn start(
+    runtime: &CursorToolRuntime,
+    call: &ToolCall,
+    context: &ExecContext,
+) -> Result<ToolStart> {
+    let message = match normalized(&call.name).as_str() {
+        "getmcptools" => {
+            let id = runtime.reserve_exec(call, context).await?;
+            codec::mcp_state_request(id, call)
+        }
+        "callmcptool" => {
+            let server = required(call, "server")?;
+            let tool = required(call, "toolName")?;
+            let definition = runtime.mcp_tool(server, tool).await.ok_or_else(|| {
+                Error::Protocol(format!(
+                    "CallMcpTool has no definition for {server}/{tool}; call GetMcpTools first"
+                ))
+            })?;
+            let id = runtime.reserve_exec(call, context).await?;
+            codec::mcp_meta_request(id, call, server, &definition)?
+        }
+        _ => {
+            let id = runtime.reserve_exec(call, context).await?;
+            codec::request(id, call, context)?
+        }
+    };
+    Ok(ToolStart {
+        messages: vec![message],
+        completion: None,
+    })
+}
+
+fn required<'a>(call: &'a ToolCall, name: &str) -> Result<&'a str> {
+    call.arguments
+        .get(name)
+        .and_then(serde_json::Value::as_str)
+        .filter(|value| !value.is_empty())
+        .ok_or_else(|| Error::Protocol(format!("{} is missing {name}", call.name)))
+}
+
+pub(super) async fn start_dynamic(
+    runtime: &CursorToolRuntime,
+    call: &ToolCall,
+    definition: &pb::McpToolDefinition,
+    context: &ExecContext,
+) -> Result<ToolStart> {
+    let id = runtime.reserve_exec(call, context).await?;
+    Ok(ToolStart {
+        messages: vec![codec::mcp_request(id, call, definition)?],
+        completion: None,
+    })
+}

cursor-server/src/cursor/tools/dispatch/interaction.rs

@@ -0,0 +1,54 @@
+//! Interaction query dispatch and approval continuation.
+
+use crate::{
+    cursor::{interaction, proto::agent::v1 as pb},
+    model::ToolCall,
+    Result,
+};
+
+use super::{normalized, InteractionContinuation, ToolStart};
+use crate::cursor::tools::{
+    codec, result,
+    runtime::{CursorToolRuntime, ExecContext, PendingInteraction},
+};
+
+pub(super) async fn start(
+    runtime: &CursorToolRuntime,
+    call: &ToolCall,
+    context: &ExecContext,
+) -> Result<ToolStart> {
+    let id = runtime.reserve_interaction(call, context).await?;
+    Ok(ToolStart {
+        messages: vec![interaction::tool_query(id, call)?],
+        completion: None,
+    })
+}
+
+pub(super) async fn resume(
+    runtime: &CursorToolRuntime,
+    pending: PendingInteraction,
+    response: &pb::InteractionResponse,
+) -> Result<InteractionContinuation> {
+    if normalized(&pending.call.name) == "webfetch"
+        && matches!(
+            response.result.as_ref(),
+            Some(pb::interaction_response::Result::WebFetchRequestResponse(
+                pb::WebFetchRequestResponse {
+                    result: Some(pb::web_fetch_request_response::Result::Approved(_)),
+                }
+            ))
+        )
+    {
+        let id = runtime
+            .reserve_exec(&pending.call, &pending.context)
+            .await?;
+        return Ok(InteractionContinuation::Message(Box::new(codec::request(
+            id,
+            &pending.call,
+            &pending.context,
+        )?)));
+    }
+    Ok(InteractionContinuation::Completed(Box::new(
+        result::from_interaction(pending, response)?,
+    )))
+}

cursor-server/src/cursor/tools/dispatch/local.rs

@@ -0,0 +1,13 @@
+//! Synchronous local tool dispatch.
+
+use crate::{model::ToolCall, Result};
+
+use super::ToolStart;
+use crate::cursor::tools::result;
+
+pub(super) fn start(call: &ToolCall, message_index: usize) -> Result<ToolStart> {
+    Ok(ToolStart {
+        messages: Vec::new(),
+        completion: Some(result::local(call, message_index)?),
+    })
+}

cursor-server/src/cursor/tools/dispatch/mod.rs

@@ -0,0 +1,63 @@
+mod await_shell;
+mod edit;
+mod exec;
+mod interaction;
+mod local;
+
+use std::collections::BTreeMap;
+
+use crate::{cursor::proto::agent::v1 as pb, model::ToolCall, Error, Result};
+
+use super::{
+    result::{ToolCompletion, ToolResultSender},
+    runtime::{CursorToolRuntime, ExecContext, PendingInteraction},
+};
+
+pub(super) struct ToolStart {
+    pub messages: Vec<pb::AgentServerMessage>,
+    pub completion: Option<ToolCompletion>,
+}
+
+pub(super) enum InteractionContinuation {
+    Message(Box<pb::AgentServerMessage>),
+    Completed(Box<ToolCompletion>),
+}
+
+pub(super) async fn start(
+    runtime: &CursorToolRuntime,
+    results: &ToolResultSender,
+    call: &ToolCall,
+    message_index: usize,
+    dynamic_mcp: &BTreeMap<String, pb::McpToolDefinition>,
+    context: &ExecContext,
+) -> Result<ToolStart> {
+    if let Some(definition) = dynamic_mcp.get(&call.name) {
+        return exec::start_dynamic(runtime, call, definition, context).await;
+    }
+
+    match normalized(&call.name).as_str() {
+        "shell" | "read" | "delete" | "grep" | "glob" | "readlints" | "task" | "callmcptool"
+        | "fetchmcpresource" | "getmcptools" => exec::start(runtime, call, context).await,
+        "write" | "strreplace" | "editnotebook" => edit::start(runtime, call, context).await,
+        "askquestion" | "websearch" | "webfetch" | "switchmode" | "createplan"
+        | "generateimage" => interaction::start(runtime, call, context).await,
+        "todowrite" | "updatecurrentstep" => local::start(call, message_index),
+        "awaitshell" => await_shell::start(runtime, results, call, context).await,
+        _ => Err(Error::Protocol(format!("unsupported tool: {}", call.name))),
+    }
+}
+
+pub(super) async fn resume_interaction(
+    runtime: &CursorToolRuntime,
+    pending: PendingInteraction,
+    response: &pb::InteractionResponse,
+) -> Result<InteractionContinuation> {
+    interaction::resume(runtime, pending, response).await
+}
+
+pub(super) fn normalized(name: &str) -> String {
+    name.chars()
+        .filter(|character| character.is_ascii_alphanumeric())
+        .flat_map(char::to_lowercase)
+        .collect()
+}

cursor-server/src/cursor/tools/edit.rs

@@ -0,0 +1,327 @@
+use serde_json::Value;
+use similar::{ChangeTag, TextDiff};
+
+use crate::{model::ToolCall, Error, Result};
+
+use crate::cursor::proto::agent::v1 as pb;
+
+#[derive(Clone, Debug)]
+pub(crate) struct EditWrite {
+    pub before: String,
+    pub after: String,
+}
+
+pub(crate) fn path(call: &ToolCall) -> Result<String> {
+    let field = if normalized(&call.name) == "editnotebook" {
+        "target_notebook"
+    } else {
+        "path"
+    };
+    string(call, field)
+}
+
+pub(crate) fn after_read(
+    call: &ToolCall,
+    result: &pb::ReadResult,
+) -> std::result::Result<EditWrite, String> {
+    let before = match result.result.as_ref() {
+        Some(pb::read_result::Result::Success(success)) => {
+            if success.truncated {
+                return Err("cannot edit a truncated Read result".into());
+            }
+            match success.output.as_ref() {
+                Some(pb::read_success::Output::Content(content)) => normalize_newlines(content),
+                Some(pb::read_success::Output::Data(_)) => {
+                    return Err("cannot edit a binary file".into());
+                }
+                None => return Err("Read result has no file content".into()),
+            }
+        }
+        Some(pb::read_result::Result::FileNotFound(_)) if normalized(&call.name) == "write" => {
+            String::new()
+        }
+        Some(pb::read_result::Result::FileNotFound(_)) => {
+            return Err("file not found".into());
+        }
+        Some(pb::read_result::Result::Error(value)) => return Err(value.error.clone()),
+        Some(pb::read_result::Result::Rejected(value)) => return Err(value.reason.clone()),
+        Some(pb::read_result::Result::PermissionDenied(_)) => {
+            return Err("read permission denied".into());
+        }
+        Some(pb::read_result::Result::InvalidFile(value)) => {
+            return Err(value.reason.clone());
+        }
+        None => return Err("Read result is empty".into()),
+    };
+    let after = match normalized(&call.name).as_str() {
+        "write" => {
+            normalize_newlines(&string(call, "contents").map_err(|error| error.to_string())?)
+        }
+        "strreplace" => replace_string(call, &before)?,
+        "editnotebook" => edit_notebook(call, &before)?,
+        _ => return Err(format!("{} is not an edit tool", call.name)),
+    };
+    Ok(EditWrite { before, after })
+}
+
+pub(crate) fn success(path: String, write: &EditWrite) -> pb::EditResult {
+    let diff = TextDiff::from_lines(&write.before, &write.after);
+    let (mut added, mut removed) = (0, 0);
+    for change in diff.iter_all_changes() {
+        match change.tag() {
+            ChangeTag::Delete => removed += 1,
+            ChangeTag::Insert => added += 1,
+            ChangeTag::Equal => {}
+        }
+    }
+    pb::EditResult {
+        result: Some(pb::edit_result::Result::Success(pb::EditSuccess {
+            path,
+            lines_added: Some(added),
+            lines_removed: Some(removed),
+            diff_string: Some(diff.unified_diff().to_string()),
+            before_full_file_content: Some(write.before.clone()),
+            after_full_file_content: write.after.clone(),
+            message: None,
+        })),
+    }
+}
+
+pub(crate) fn failure(path: String, error: impl Into<String>) -> pb::EditResult {
+    let error = error.into();
+    pb::EditResult {
+        result: Some(pb::edit_result::Result::Error(pb::EditError {
+            path,
+            error: error.clone(),
+            model_visible_error: Some(error),
+        })),
+    }
+}
+
+pub(crate) fn normalize_newlines(value: &str) -> String {
+    let normalized = value.replace("\r\n", "\n");
+    normalized.replace('\r', "\n")
+}
+
+fn replace_string(call: &ToolCall, before: &str) -> std::result::Result<String, String> {
+    let old = normalize_newlines(&string(call, "old_string").map_err(|error| error.to_string())?);
+    let new = normalize_newlines(&string(call, "new_string").map_err(|error| error.to_string())?);
+    if old.is_empty() {
+        return Err("old_string must not be empty".into());
+    }
+    let occurrences = before.match_indices(&old).count();
+    let replace_all = call
+        .arguments
+        .get("replace_all")
+        .and_then(Value::as_bool)
+        .unwrap_or(false);
+    match (replace_all, occurrences) {
+        (_, 0) => Err("old_string was not found".into()),
+        (false, 1) => Ok(before.replacen(&old, &new, 1)),
+        (false, count) => Err(format!(
+            "old_string is not unique; found {count} occurrences"
+        )),
+        (true, _) => Ok(before.replace(&old, &new)),
+    }
+}
+
+fn edit_notebook(call: &ToolCall, before: &str) -> std::result::Result<String, String> {
+    let mut notebook: Value =
+        serde_json::from_str(before).map_err(|error| format!("invalid notebook JSON: {error}"))?;
+    let cells = notebook
+        .get_mut("cells")
+        .and_then(Value::as_array_mut)
+        .ok_or_else(|| "notebook has no cells array".to_string())?;
+    let index = call
+        .arguments
+        .get("cell_idx")
+        .and_then(Value::as_u64)
+        .and_then(|value| usize::try_from(value).ok())
+        .ok_or_else(|| "EditNotebook is missing cell_idx".to_string())?;
+    let new = normalize_newlines(&string(call, "new_string").map_err(|error| error.to_string())?);
+    if call
+        .arguments
+        .get("is_new_cell")
+        .and_then(Value::as_bool)
+        .unwrap_or(false)
+    {
+        if index > cells.len() {
+            return Err(format!("cell_idx {index} is past the end of the notebook"));
+        }
+        let language = string(call, "cell_language").map_err(|error| error.to_string())?;
+        let cell_type = if language == "markdown" || language == "raw" {
+            language.as_str()
+        } else {
+            "code"
+        };
+        let mut cell = serde_json::json!({
+            "cell_type": cell_type,
+            "metadata": {},
+            "source": source_lines(&new),
+        });
+        if cell_type == "code" {
+            cell["execution_count"] = Value::Null;
+            cell["outputs"] = Value::Array(Vec::new());
+        }
+        cells.insert(index, cell);
+    } else {
+        let cell = cells
+            .get_mut(index)
+            .ok_or_else(|| format!("cell_idx {index} does not exist"))?;
+        let source = cell
+            .get("source")
+            .map(notebook_source)
+            .transpose()?
+            .unwrap_or_default();
+        let old =
+            normalize_newlines(&string(call, "old_string").map_err(|error| error.to_string())?);
+        let occurrences = source.match_indices(&old).count();
+        let edited = match occurrences {
+            0 => return Err("old_string was not found in the notebook cell".into()),
+            1 => source.replacen(&old, &new, 1),
+            count => {
+                return Err(format!(
+                    "old_string is not unique in the notebook cell; found {count} occurrences"
+                ))
+            }
+        };
+        cell["source"] = Value::Array(source_lines(&edited));
+    }
+    serde_json::to_string_pretty(&notebook)
+        .map(|value| format!("{value}\n"))
+        .map_err(|error| error.to_string())
+}
+
+fn notebook_source(value: &Value) -> std::result::Result<String, String> {
+    match value {
+        Value::String(value) => Ok(normalize_newlines(value)),
+        Value::Array(lines) => lines
+            .iter()
+            .map(|line| {
+                line.as_str()
+                    .ok_or_else(|| "notebook cell source contains a non-string".to_string())
+            })
+            .collect::<std::result::Result<Vec<_>, _>>()
+            .map(|lines| normalize_newlines(&lines.concat())),
+        _ => Err("notebook cell source is not text".into()),
+    }
+}
+
+fn source_lines(value: &str) -> Vec<Value> {
+    if value.is_empty() {
+        Vec::new()
+    } else {
+        value
+            .split_inclusive('\n')
+            .map(|line| Value::String(line.to_string()))
+            .collect()
+    }
+}
+
+fn string(call: &ToolCall, field: &str) -> Result<String> {
+    call.arguments
+        .get(field)
+        .and_then(Value::as_str)
+        .map(str::to_owned)
+        .ok_or_else(|| Error::Protocol(format!("{} is missing {field}", call.name)))
+}
+
+fn normalized(value: &str) -> String {
+    value
+        .chars()
+        .filter(|character| character.is_ascii_alphanumeric())
+        .flat_map(char::to_lowercase)
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use serde_json::json;
+
+    use super::*;
+
+    fn call(name: &str, arguments: Value) -> ToolCall {
+        ToolCall {
+            index: 0,
+            call_id: "call\nfc_1".into(),
+            model_call_id: "model".into(),
+            name: name.into(),
+            arguments_text: String::new(),
+            arguments,
+        }
+    }
+
+    fn read(content: &str) -> pb::ReadResult {
+        pb::ReadResult {
+            result: Some(pb::read_result::Result::Success(pb::ReadSuccess {
+                output: Some(pb::read_success::Output::Content(content.into())),
+                ..Default::default()
+            })),
+        }
+    }
+
+    #[test]
+    fn write_and_str_replace_use_one_lf_canonical_form() {
+        let write = after_read(
+            &call("Write", json!({"path":"/a","contents":"new\rline\r\n"})),
+            &read("old\r\nline\r"),
+        )
+        .unwrap();
+        assert_eq!(write.before, "old\nline\n");
+        assert_eq!(write.after, "new\nline\n");
+
+        let replacement = after_read(
+            &call(
+                "StrReplace",
+                json!({"path":"/a","old_string":"old\nline","new_string":"new\r\nline"}),
+            ),
+            &read("old\r\nline\r\nrest"),
+        )
+        .unwrap();
+        assert_eq!(replacement.after, "new\nline\nrest");
+    }
+
+    #[test]
+    fn str_replace_requires_one_match_unless_replace_all_is_explicit() {
+        let ambiguous = after_read(
+            &call(
+                "StrReplace",
+                json!({"path":"/a","old_string":"same","new_string":"new"}),
+            ),
+            &read("same\nsame\n"),
+        )
+        .unwrap_err();
+        assert_eq!(ambiguous, "old_string is not unique; found 2 occurrences");
+
+        let all = after_read(
+            &call(
+                "StrReplace",
+                json!({
+                    "path":"/a", "old_string":"same", "new_string":"new",
+                    "replace_all":true
+                }),
+            ),
+            &read("same\rsame\r\n"),
+        )
+        .unwrap();
+        assert_eq!(all.after, "new\nnew\n");
+    }
+
+    #[test]
+    fn notebook_edit_targets_one_cell_and_preserves_lf() {
+        let notebook = r#"{"cells":[{"cell_type":"code","source":["old\r\n","line"]}],"metadata":{},"nbformat":4,"nbformat_minor":5}"#;
+        let edit = after_read(
+            &call(
+                "EditNotebook",
+                json!({
+                    "target_notebook":"/a.ipynb", "cell_idx":0, "is_new_cell":false,
+                    "cell_language":"python", "old_string":"old\nline", "new_string":"new\r\nline"
+                }),
+            ),
+            &read(notebook),
+        )
+        .unwrap();
+        let parsed: Value = serde_json::from_str(&edit.after).unwrap();
+        assert_eq!(parsed["cells"][0]["source"], json!(["new\n", "line"]));
+    }
+}

cursor-server/src/cursor/tools/mod.rs

@@ -0,0 +1,163 @@
+use std::collections::{BTreeMap, HashSet};
+
+pub mod codec;
+mod dispatch;
+pub(crate) mod edit;
+pub(crate) mod result;
+pub mod runtime;
+pub(crate) mod stream;
+
+use crate::{
+    model::{CanonicalMessage, MessageContent, Role, ToolCall},
+    Error, Result,
+};
+
+use self::result::{ToolCompletion, ToolResultSender};
+use super::{interaction, proto::agent::v1 as pb};
+use runtime::{CursorToolRuntime, ExecContext};
+
+#[derive(Clone)]
+pub struct ToolDispatcher {
+    runtime: CursorToolRuntime,
+    results: ToolResultSender,
+}
+
+pub struct DispatchedTool {
+    pub messages: Vec<pb::AgentServerMessage>,
+    pub completion: Option<ToolCompletion>,
+}
+
+pub struct ToolBatchState<'a> {
+    pub completed: &'a HashSet<String>,
+    pub started: &'a HashSet<String>,
+    pub response_text: &'a str,
+    pub response_thinking: &'a str,
+}
+
+pub enum ClientToolEvent {
+    Message(Box<pb::AgentServerMessage>),
+    Completed(Box<ToolCompletion>),
+}
+
+impl ToolDispatcher {
+    pub fn new(runtime: CursorToolRuntime) -> Self {
+        let (results, _) = result::tool_result_channel();
+        Self::with_results(runtime, results)
+    }
+
+    pub fn with_results(runtime: CursorToolRuntime, results: ToolResultSender) -> Self {
+        Self { runtime, results }
+    }
+
+    pub async fn start_batch(
+        &self,
+        calls: &[ToolCall],
+        state: ToolBatchState<'_>,
+        messages: &[CanonicalMessage],
+        dynamic_mcp: &BTreeMap<String, pb::McpToolDefinition>,
+        context: &ExecContext,
+    ) -> Result<Vec<DispatchedTool>> {
+        let first_tool_index = current_turn_step_count(messages)
+            + usize::from(!state.response_thinking.is_empty())
+            + usize::from(!state.response_text.is_empty())
+            + 1;
+        let mut dispatched = Vec::new();
+        for (position, call) in calls.iter().enumerate() {
+            if state.completed.contains(&call.call_id) {
+                continue;
+            }
+            dispatched.push(
+                self.start(
+                    call,
+                    first_tool_index + position,
+                    !state.started.contains(&call.call_id),
+                    dynamic_mcp,
+                    context,
+                )
+                .await?,
+            );
+        }
+        Ok(dispatched)
+    }
+
+    async fn start(
+        &self,
+        call: &ToolCall,
+        message_index: usize,
+        publish_started: bool,
+        dynamic_mcp: &BTreeMap<String, pb::McpToolDefinition>,
+        context: &ExecContext,
+    ) -> Result<DispatchedTool> {
+        let mut messages = if publish_started {
+            vec![interaction::tool_started(call)?]
+        } else {
+            Vec::new()
+        };
+        let started = dispatch::start(
+            &self.runtime,
+            &self.results,
+            call,
+            message_index,
+            dynamic_mcp,
+            context,
+        )
+        .await?;
+        messages.extend(started.messages);
+        Ok(DispatchedTool {
+            messages,
+            completion: started.completion,
+        })
+    }
+
+    pub async fn interaction_response(
+        &self,
+        response: &pb::InteractionResponse,
+    ) -> Result<ClientToolEvent> {
+        let pending = match self.runtime.take_interaction(response.id).await {
+            Some(pending) => pending,
+            None if self.runtime.completed_call(response.id).await.is_some() => {
+                return Err(Error::Protocol(format!(
+                    "duplicate terminal InteractionResponse id: {}",
+                    response.id
+                )));
+            }
+            None => {
+                return Err(Error::Protocol(format!(
+                    "unknown InteractionResponse id: {}",
+                    response.id
+                )));
+            }
+        };
+        Ok(
+            match dispatch::resume_interaction(&self.runtime, pending, response).await? {
+                dispatch::InteractionContinuation::Message(message) => {
+                    ClientToolEvent::Message(message)
+                }
+                dispatch::InteractionContinuation::Completed(completion) => {
+                    ClientToolEvent::Completed(completion)
+                }
+            },
+        )
+    }
+}
+
+fn current_turn_step_count(messages: &[CanonicalMessage]) -> usize {
+    let turn_start = messages
+        .iter()
+        .rposition(|message| message.role == Role::User)
+        .map_or(0, |position| position + 1);
+    messages[turn_start..]
+        .iter()
+        .map(|message| match &message.content {
+            MessageContent::Assistant {
+                text,
+                thinking,
+                tool_calls,
+                ..
+            } => {
+                usize::from(!thinking.is_empty()) + usize::from(!text.is_empty()) + tool_calls.len()
+            }
+            _ => 0,
+        })
+        .sum()
+}

cursor-server/src/cursor/tools/result/await_shell.rs

@@ -0,0 +1,143 @@
+use serde_json::Value;
+
+use crate::{
+    cursor::proto::agent::v1 as pb,
+    model::{ToolCall, ToolResult},
+    Error, Result,
+};
+
+use super::{now_ms, ToolCompletion};
+use crate::cursor::tools::runtime::{ExecStage, PendingExec};
+
+pub(crate) fn await_result(
+    pending: PendingExec,
+    output_length: u64,
+    regex_match: Option<String>,
+    exit_code: Option<i32>,
+) -> Result<ToolCompletion> {
+    let ExecStage::Await(state) = &pending.stage else {
+        return Err(Error::Protocol(
+            "AwaitShell completion reached a non-await execution stage".into(),
+        ));
+    };
+    let runtime_ms = now_ms().saturating_sub(pending.started_at_ms);
+    let result = if exit_code.is_some() {
+        pb::await_success::AwaitResult::Complete(pb::AwaitTaskComplete {
+            task_id: state.task_id.clone(),
+            runtime_ms,
+            output_file_path: state.output_file_path.clone(),
+            output_length,
+            regex_requested: state.regex.is_some(),
+            regex_match,
+            exit_code,
+            wake_reason: Some("task_complete".into()),
+        })
+    } else {
+        pb::await_success::AwaitResult::StillRunning(pb::AwaitTaskStillRunning {
+            task_id: state.task_id.clone(),
+            runtime_ms,
+            output_file_path: state.output_file_path.clone(),
+            output_length,
+            regex_requested: state.regex.is_some(),
+            regex_match,
+            wake_reason: Some("timeout_or_pattern".into()),
+        })
+    };
+    let content = serde_json::json!({
+        "task_id": state.task_id,
+        "output_file_path": state.output_file_path,
+        "output_length": output_length,
+        "exit_code": exit_code,
+    })
+    .to_string();
+    completion(
+        &pending,
+        content,
+        false,
+        pb::await_result::Result::Success(pb::AwaitSuccess {
+            await_result: Some(result),
+        }),
+    )
+}
+
+pub(crate) fn await_error(pending: PendingExec, error: &str) -> Result<ToolCompletion> {
+    completion(
+        &pending,
+        error.into(),
+        true,
+        pb::await_result::Result::Error(pb::AwaitError {
+            error: error.into(),
+        }),
+    )
+}
+
+fn completion(
+    pending: &PendingExec,
+    content: String,
+    is_error: bool,
+    result: pb::await_result::Result,
+) -> Result<ToolCompletion> {
+    let ExecStage::Await(state) = &pending.stage else {
+        return Err(Error::Protocol(
+            "AwaitShell completion reached a non-await execution stage".into(),
+        ));
+    };
+    Ok(ToolCompletion::new(
+        &pending.call,
+        pending.started_at_ms,
+        ToolResult {
+            call_id: pending.call.call_id.clone(),
+            content,
+            is_error,
+        },
+        pb::tool_call::Tool::AwaitToolCall(pb::AwaitToolCall {
+            args: Some(pb::AwaitArgs {
+                task_id: state.task_id.clone(),
+                block_until_ms: pending
+                    .call
+                    .arguments
+                    .get("block_until_ms")
+                    .and_then(Value::as_u64)
+                    .map(|value| value as u32),
+                regex: state.regex.clone(),
+            }),
+            result: Some(pb::AwaitResult {
+                result: Some(result),
+            }),
+        }),
+    ))
+}
+
+pub(crate) fn await_sleep(call: &ToolCall, runtime_ms: u64) -> ToolCompletion {
+    ToolCompletion::new(
+        call,
+        now_ms().saturating_sub(runtime_ms),
+        ToolResult {
+            call_id: call.call_id.clone(),
+            content: format!("Waited {runtime_ms} ms"),
+            is_error: false,
+        },
+        pb::tool_call::Tool::AwaitToolCall(pb::AwaitToolCall {
+            args: Some(pb::AwaitArgs {
+                task_id: String::new(),
+                block_until_ms: Some(runtime_ms as u32),
+                regex: None,
+            }),
+            result: Some(pb::AwaitResult {
+                result: Some(pb::await_result::Result::Success(pb::AwaitSuccess {
+                    await_result: Some(pb::await_success::AwaitResult::StillRunning(
+                        pb::AwaitTaskStillRunning {
+                            task_id: String::new(),
+                            runtime_ms,
+                            output_file_path: String::new(),
+                            output_length: 0,
+                            regex_requested: false,
+                            regex_match: None,
+                            wake_reason: Some("sleep_complete".into()),
+                        },
+                    )),
+                })),
+            }),
+        }),
+    )
+}

cursor-server/src/cursor/tools/result/exec/mod.rs

@@ -0,0 +1,110 @@
+mod output;
+mod render;
+
+use crate::{
+    cursor::{interaction, proto::agent::v1 as pb},
+    model::ToolResult,
+    Error, Result,
+};
+
+use super::{mcp_state, ToolCompletion};
+use crate::cursor::tools::{
+    edit,
+    runtime::{ExecStage, PendingExec},
+};
+
+pub(crate) fn from_exec(
+    pending: PendingExec,
+    wire_result: &pb::exec_client_message::Message,
+) -> Result<ToolCompletion> {
+    use pb::{exec_client_message::Message, tool_call::Tool};
+    if let Message::McpStateExecResult(result) = wire_result {
+        return mcp_state::complete(pending, result);
+    }
+    let call = &pending.call;
+    let (content, is_error) = output::output(wire_result, call)?;
+    let mut rendered = interaction::render_tool_call(call, false)?;
+    match (rendered.tool.as_mut(), wire_result) {
+        (Some(Tool::ShellToolCall(tool)), Message::ShellResult(result))
+        | (Some(Tool::ShellToolCall(tool)), Message::MiniSweAgentBashResult(result)) => {
+            tool.result = Some(result.clone());
+        }
+        (Some(Tool::DeleteToolCall(tool)), Message::DeleteResult(result)) => {
+            tool.result = Some(result.clone());
+        }
+        (Some(Tool::GrepToolCall(tool)), Message::GrepResult(result)) => {
+            tool.result = Some(result.clone());
+        }
+        (Some(Tool::GlobToolCall(tool)), Message::GrepResult(result)) => {
+            tool.result = Some(render::glob(result)?);
+        }
+        (Some(Tool::ReadToolCall(tool)), Message::ReadResult(result))
+        | (Some(Tool::ReadToolCall(tool)), Message::RedactedReadResult(result)) => {
+            tool.result = Some(render::read(result, call)?);
+        }
+        (Some(Tool::ReadLintsToolCall(tool)), Message::DiagnosticsResult(result)) => {
+            tool.result = Some(render::diagnostics(result)?);
+        }
+        (Some(Tool::McpToolCall(tool)), Message::McpResult(result)) => {
+            tool.result = Some(render::mcp(result)?);
+        }
+        (Some(Tool::ReadMcpResourceToolCall(tool)), Message::ReadMcpResourceExecResult(result)) => {
+            tool.result = Some(result.clone());
+        }
+        (Some(Tool::WebFetchToolCall(tool)), Message::FetchResult(result)) => {
+            tool.result = Some(render::web_fetch(result)?);
+        }
+        (Some(Tool::TaskToolCall(tool)), Message::SubagentResult(result)) => {
+            tool.result = Some(render::task(result)?);
+        }
+        (Some(Tool::EditToolCall(tool)), Message::WriteResult(result)) => {
+            tool.result = Some(match (&pending.stage, result.result.as_ref()) {
+                (ExecStage::EditWrite(write), Some(pb::write_result::Result::Success(success))) => {
+                    edit::success(success.path.clone(), write)
+                }
+                _ => render::write(result)?,
+            });
+        }
+        _ => {
+            return Err(Error::Protocol(format!(
+                "unexpected Exec result for tool {}",
+                call.name
+            )));
+        }
+    }
+    let tool = rendered.tool.ok_or_else(|| {
+        Error::Protocol(format!("tool {} has no Cursor representation", call.name))
+    })?;
+    Ok(ToolCompletion::new(
+        call,
+        pending.started_at_ms,
+        ToolResult {
+            call_id: call.call_id.clone(),
+            content,
+            is_error,
+        },
+        tool,
+    ))
+}
+
+pub(crate) fn edit_failure(pending: PendingExec, error: String) -> Result<ToolCompletion> {
+    let call = &pending.call;
+    let mut rendered = interaction::render_tool_call(call, false)?;
+    let Some(pb::tool_call::Tool::EditToolCall(mut tool)) = rendered.tool.take() else {
+        return Err(Error::Protocol(format!(
+            "{} is not an edit tool",
+            call.name
+        )));
+    };
+    tool.result = Some(edit::failure(edit::path(call)?, error.clone()));
+    Ok(ToolCompletion::new(
+        call,
+        pending.started_at_ms,
+        ToolResult {
+            call_id: call.call_id.clone(),
+            content: error,
+            is_error: true,
+        },
+        pb::tool_call::Tool::EditToolCall(tool),
+    ))
+}

cursor-server/src/cursor/tools/result/exec/output.rs

@@ -0,0 +1,278 @@
+use crate::{cursor::proto::agent::v1 as pb, model::ToolCall, Error, Result};
+
+pub(super) fn output(
+    message: &pb::exec_client_message::Message,
+    call: &ToolCall,
+) -> Result<(String, bool)> {
+    use pb::exec_client_message::Message;
+    match message {
+        Message::ShellResult(value) | Message::MiniSweAgentBashResult(value) => shell(value),
+        Message::ReadResult(value) | Message::RedactedReadResult(value) => read(value),
+        Message::WriteResult(value) => write(value),
+        Message::DeleteResult(value) => delete(value),
+        Message::GrepResult(value) => grep(value),
+        Message::DiagnosticsResult(value) => diagnostics(value),
+        Message::McpResult(value) => mcp(value),
+        Message::ReadMcpResourceExecResult(value) => read_mcp(value),
+        Message::FetchResult(value) => fetch(value),
+        Message::SubagentResult(value) => task(value, call),
+        _ => Err(Error::Protocol(
+            "unsupported terminal ExecClientMessage".into(),
+        )),
+    }
+}
+
+fn shell(value: &pb::ShellResult) -> Result<(String, bool)> {
+    use pb::shell_result::Result as R;
+    let output = match value.result.as_ref().ok_or_else(|| missing("shell"))? {
+        R::Success(success) if value.is_background == Some(true) => {
+            let mut fields = vec![format!("shell_id={}", success.shell_id.unwrap_or_default())];
+            if let Some(pid) = success.pid.or(value.pid) {
+                fields.push(format!("pid={pid}"));
+            }
+            if let Some(folder) = value.terminals_folder.as_deref().filter(|v| !v.is_empty()) {
+                fields.push(format!("terminals_folder={folder}"));
+            }
+            let output = streams(&success.stdout, &success.stderr);
+            let prefix = format!("shell running in background {}", fields.join(" "));
+            return Ok((
+                if output == "shell completed without output" {
+                    prefix
+                } else {
+                    format!("{prefix}\n{output}")
+                },
+                false,
+            ));
+        }
+        R::Success(success) => return Ok((streams(&success.stdout, &success.stderr), false)),
+        R::Failure(failure) => streams(&failure.stdout, &failure.stderr),
+        R::Timeout(timeout) => format!(
+            "shell timed out after {}ms in {}",
+            timeout.timeout_ms, timeout.working_directory
+        ),
+        R::Rejected(rejected) => rejected.reason.clone(),
+        R::SpawnError(error) => error.error.clone(),
+        R::PermissionDenied(denied) => denied.error.clone(),
+    };
+    Ok((output, true))
+}
+
+fn streams(stdout: &str, stderr: &str) -> String {
+    match (stdout.is_empty(), stderr.is_empty()) {
+        (false, false) => format!("{stdout}\n\n<stderr>\n{stderr}\n</stderr>"),
+        (false, true) => stdout.into(),
+        (true, false) => stderr.into(),
+        (true, true) => "shell completed without output".into(),
+    }
+}
+
+fn read(value: &pb::ReadResult) -> Result<(String, bool)> {
+    use pb::{read_result::Result as R, read_success::Output};
+    match value.result.as_ref().ok_or_else(|| missing("read"))? {
+        R::Success(success) => Ok((
+            match success.output.as_ref() {
+                Some(Output::Content(text)) => text.clone(),
+                Some(Output::Data(bytes)) => format!("read binary bytes={}", bytes.len()),
+                None => format!("read success path={}", success.path),
+            },
+            false,
+        )),
+        R::Error(error) => Ok((error.error.clone(), true)),
+        R::Rejected(rejected) => Ok((rejected.reason.clone(), true)),
+        R::FileNotFound(value) => Ok((format!("file not found: {}", value.path), true)),
+        R::PermissionDenied(value) => Ok((format!("permission denied: {}", value.path), true)),
+        R::InvalidFile(value) => Ok((value.reason.clone(), true)),
+    }
+}
+
+fn write(value: &pb::WriteResult) -> Result<(String, bool)> {
+    use pb::write_result::Result as R;
+    match value.result.as_ref().ok_or_else(|| missing("write"))? {
+        R::Success(success) => Ok((
+            success.file_content_after_write.clone().unwrap_or_else(|| {
+                format!(
+                    "write success path={} lines={}",
+                    success.path, success.lines_created
+                )
+            }),
+            false,
+        )),
+        R::PermissionDenied(value) => Ok((value.error.clone(), true)),
+        R::NoSpace(value) => Ok((format!("no space left: {}", value.path), true)),
+        R::Error(value) => Ok((value.error.clone(), true)),
+        R::Rejected(value) => Ok((value.reason.clone(), true)),
+    }
+}
+
+fn delete(value: &pb::DeleteResult) -> Result<(String, bool)> {
+    use pb::delete_result::Result as R;
+    match value.result.as_ref().ok_or_else(|| missing("delete"))? {
+        R::Success(value) => Ok((format!("delete success path={}", value.path), false)),
+        R::FileNotFound(value) => Ok((format!("file not found: {}", value.path), true)),
+        R::NotFile(value) => Ok((format!("not file: {}", value.path), true)),
+        R::PermissionDenied(value) => Ok((value.client_visible_error.clone(), true)),
+        R::FileBusy(value) => Ok((format!("file busy: {}", value.path), true)),
+        R::Rejected(value) => Ok((value.reason.clone(), true)),
+        R::Error(value) => Ok((value.error.clone(), true)),
+    }
+}
+
+fn grep(value: &pb::GrepResult) -> Result<(String, bool)> {
+    use pb::grep_result::Result as R;
+    match value.result.as_ref().ok_or_else(|| missing("grep"))? {
+        R::Success(value) => Ok((
+            format!(
+                "grep success pattern={} mode={}",
+                value.pattern, value.output_mode
+            ),
+            false,
+        )),
+        R::Error(value) => Ok((value.error.clone(), true)),
+    }
+}
+
+fn diagnostics(value: &pb::DiagnosticsResult) -> Result<(String, bool)> {
+    use pb::diagnostics_result::Result as R;
+    match value
+        .result
+        .as_ref()
+        .ok_or_else(|| missing("diagnostics"))?
+    {
+        R::Success(value) => Ok((
+            format!(
+                "diagnostics path={} count={}",
+                value.path, value.total_diagnostics
+            ),
+            false,
+        )),
+        R::Error(value) => Ok((value.error.clone(), true)),
+        R::Rejected(value) => Ok((value.reason.clone(), true)),
+        R::FileNotFound(value) => Ok((format!("file not found: {}", value.path), true)),
+        R::PermissionDenied(value) => Ok((format!("permission denied: {}", value.path), true)),
+    }
+}
+
+fn mcp(value: &pb::McpResult) -> Result<(String, bool)> {
+    use pb::mcp_result::Result as R;
+    match value.result.as_ref().ok_or_else(|| missing("mcp"))? {
+        R::Success(value) => Ok((mcp_content(value)?, value.is_error)),
+        R::Error(value) => Ok((value.error.clone(), true)),
+        R::Rejected(value) => Ok((value.reason.clone(), true)),
+        R::PermissionDenied(value) => Ok((value.error.clone(), true)),
+        R::ToolNotFound(value) => Ok((format!("MCP tool not found: {}", value.name), true)),
+        R::ServerNotFound(value) => Ok((format!("MCP server not found: {}", value.name), true)),
+        R::Approved(_) => Err(Error::Protocol("MCP approval is not terminal".into())),
+    }
+}
+
+fn mcp_content(success: &pb::McpSuccess) -> Result<String> {
+    let mut content = Vec::new();
+    for item in &success.content {
+        match item.content.as_ref() {
+            Some(pb::mcp_tool_result_content_item::Content::Text(text)) => {
+                if !text.text.is_empty() {
+                    content.push(text.text.clone());
+                }
+                if let Some(location) = &text.output_location {
+                    content.push(format!(
+                        "MCP output file: {} ({} bytes, {} lines)",
+                        location.file_path, location.size_bytes, location.line_count
+                    ));
+                }
+            }
+            Some(pb::mcp_tool_result_content_item::Content::Image(image)) => content.push(format!(
+                "MCP image: {} ({} bytes)",
+                image.mime_type,
+                image.data.len()
+            )),
+            None => {}
+        }
+    }
+    if let Some(structured) = &success.structured_content {
+        let value = serde_json::Value::Object(
+            structured
+                .fields
+                .iter()
+                .map(|(key, value)| (key.clone(), super::super::prost_json(value)))
+                .collect(),
+        );
+        content.push(serde_json::to_string_pretty(&value)?);
+    }
+    Ok(if content.is_empty() {
+        "MCP tool completed without content".into()
+    } else {
+        content.join("\n\n")
+    })
+}
+
+fn read_mcp(value: &pb::ReadMcpResourceExecResult) -> Result<(String, bool)> {
+    use pb::read_mcp_resource_exec_result::Result as R;
+    match value
+        .result
+        .as_ref()
+        .ok_or_else(|| missing("read MCP resource"))?
+    {
+        R::Success(value) => Ok((
+            match value.content.as_ref() {
+                Some(pb::read_mcp_resource_success::Content::Text(text)) => text.clone(),
+                Some(pb::read_mcp_resource_success::Content::Blob(blob)) => {
+                    format!("read MCP resource blob={}", blob.len())
+                }
+                None => format!("read MCP resource uri={}", value.uri),
+            },
+            false,
+        )),
+        R::Error(value) => Ok((value.error.clone(), true)),
+        R::Rejected(value) => Ok((value.reason.clone(), true)),
+        R::NotFound(value) => Ok((format!("MCP resource not found: {}", value.uri), true)),
+    }
+}
+
+fn fetch(value: &pb::FetchResult) -> Result<(String, bool)> {
+    use pb::fetch_result::Result as R;
+    match value.result.as_ref().ok_or_else(|| missing("web fetch"))? {
+        R::Success(value) => Ok((value.content.clone(), false)),
+        R::Error(value) => Ok((value.error.clone(), true)),
+    }
+}
+
+fn task(value: &pb::SubagentResult, call: &ToolCall) -> Result<(String, bool)> {
+    use pb::subagent_result::Result as R;
+    match value.result.as_ref().ok_or_else(|| missing("subagent"))? {
+        R::Success(value) if creates_subagent(call) => {
+            let name = call
+                .arguments
+                .get("description")
+                .and_then(serde_json::Value::as_str)
+                .filter(|name| !name.is_empty())
+                .ok_or_else(|| Error::Protocol("Task call is missing description".into()))?;
+            if value.agent_id.is_empty() {
+                return Err(Error::Protocol("Task result is missing agent_id".into()));
+            }
+            let identity = format!("Subagent name: {name}\nSubagent ID: {}", value.agent_id);
+            let content = value
+                .final_message
+                .as_deref()
+                .filter(|message| !message.is_empty())
+                .map_or(identity.clone(), |message| {
+                    format!("{identity}\n\n{message}")
+                });
+            Ok((content, false))
+        }
+        R::Success(value) => Ok((value.final_message.clone().unwrap_or_default(), false)),
+        R::Error(value) => Ok((value.error.clone(), true)),
+    }
+}
+
+fn creates_subagent(call: &ToolCall) -> bool {
+    matches!(
+        call.arguments
+            .get("resume")
+            .and_then(serde_json::Value::as_str),
+        None | Some("self")
+    )
+}
+
+fn missing(name: &str) -> Error {
+    Error::Protocol(format!("{name} returned no result"))
+}

cursor-server/src/cursor/tools/result/exec/render.rs

@@ -0,0 +1,258 @@
+use serde_json::Value;
+
+use crate::{cursor::proto::agent::v1 as pb, model::ToolCall, Error, Result};
+
+pub(super) fn read(result: &pb::ReadResult, call: &ToolCall) -> Result<pb::ReadToolResult> {
+    use pb::{read_result::Result as Input, read_tool_result::Result as Output};
+    let result = match result.result.as_ref() {
+        Some(Input::Success(success)) => Output::Success(pb::ReadToolSuccess {
+            is_empty: match success.output.as_ref() {
+                Some(pb::read_success::Output::Content(content)) => content.is_empty(),
+                Some(pb::read_success::Output::Data(data)) => data.is_empty(),
+                None => true,
+            },
+            exceeded_limit: success.truncated,
+            total_lines: success.total_lines.max(0) as u32,
+            file_size: success.file_size.max(0).min(u32::MAX as i64) as u32,
+            path: success.path.clone(),
+            read_range: read_range(call),
+            include_line_numbers: call
+                .arguments
+                .get("include_line_numbers")
+                .and_then(Value::as_bool),
+            output: success.output.as_ref().map(|output| match output {
+                pb::read_success::Output::Content(content) => {
+                    pb::read_tool_success::Output::Content(content.clone())
+                }
+                pb::read_success::Output::Data(data) => {
+                    pb::read_tool_success::Output::Data(data.clone())
+                }
+            }),
+            ..Default::default()
+        }),
+        Some(Input::Error(value)) => error_read(&value.error),
+        Some(Input::Rejected(value)) => error_read(&value.reason),
+        Some(Input::FileNotFound(value)) => error_read(&format!("file not found: {}", value.path)),
+        Some(Input::PermissionDenied(value)) => {
+            error_read(&format!("permission denied: {}", value.path))
+        }
+        Some(Input::InvalidFile(value)) => error_read(&value.reason),
+        None => return Err(missing("read")),
+    };
+    Ok(pb::ReadToolResult {
+        result: Some(result),
+    })
+}
+
+fn error_read(message: &str) -> pb::read_tool_result::Result {
+    pb::read_tool_result::Result::Error(pb::ReadToolError {
+        error_message: message.into(),
+    })
+}
+
+fn read_range(call: &ToolCall) -> Option<pb::ReadRange> {
+    let start_line = call
+        .arguments
+        .get("offset")
+        .and_then(Value::as_u64)
+        .unwrap_or(0) as u32;
+    let limit = call
+        .arguments
+        .get("limit")
+        .and_then(Value::as_u64)
+        .map(|value| value as u32)?;
+    Some(pb::ReadRange {
+        start_line,
+        end_line: start_line.saturating_add(limit),
+    })
+}
+
+pub(super) fn write(result: &pb::WriteResult) -> Result<pb::EditResult> {
+    use pb::{edit_result::Result as Output, write_result::Result as Input};
+    let result = match result.result.as_ref() {
+        Some(Input::Success(success)) => Output::Success(pb::EditSuccess {
+            path: success.path.clone(),
+            after_full_file_content: success.file_content_after_write.clone().unwrap_or_default(),
+            ..Default::default()
+        }),
+        Some(Input::PermissionDenied(value)) => {
+            Output::WritePermissionDenied(pb::EditWritePermissionDenied {
+                path: value.path.clone(),
+                error: value.error.clone(),
+                is_readonly: value.is_readonly,
+            })
+        }
+        Some(Input::NoSpace(value)) => edit_error(&value.path, "no space left"),
+        Some(Input::Error(value)) => edit_error(&value.path, &value.error),
+        Some(Input::Rejected(value)) => Output::Rejected(pb::EditRejected {
+            path: value.path.clone(),
+            reason: value.reason.clone(),
+        }),
+        None => return Err(missing("write")),
+    };
+    Ok(pb::EditResult {
+        result: Some(result),
+    })
+}
+
+fn edit_error(path: &str, message: &str) -> pb::edit_result::Result {
+    pb::edit_result::Result::Error(pb::EditError {
+        path: path.into(),
+        error: message.into(),
+        model_visible_error: Some(message.into()),
+    })
+}
+
+pub(super) fn diagnostics(result: &pb::DiagnosticsResult) -> Result<pb::ReadLintsToolResult> {
+    use pb::{diagnostics_result::Result as Input, read_lints_tool_result::Result as Output};
+    let result = match result.result.as_ref() {
+        Some(Input::Success(success)) => {
+            let diagnostics = success
+                .diagnostics
+                .iter()
+                .map(|diagnostic| pb::DiagnosticItem {
+                    severity: diagnostic.severity,
+                    range: diagnostic.range.as_ref().map(|range| pb::DiagnosticRange {
+                        start: range.start,
+                        end: range.end,
+                    }),
+                    message: diagnostic.message.clone(),
+                    source: diagnostic.source.clone(),
+                    code: diagnostic.code.clone(),
+                    is_stale: diagnostic.is_stale,
+                })
+                .collect::<Vec<_>>();
+            Output::Success(pb::ReadLintsToolSuccess {
+                file_diagnostics: vec![pb::FileDiagnostics {
+                    path: success.path.clone(),
+                    diagnostics_count: diagnostics.len() as i32,
+                    diagnostics,
+                }],
+                total_files: 1,
+                total_diagnostics: success.total_diagnostics,
+            })
+        }
+        Some(Input::Error(value)) => lint_error(&value.error),
+        Some(Input::Rejected(value)) => lint_error(&value.reason),
+        Some(Input::FileNotFound(value)) => lint_error(&format!("file not found: {}", value.path)),
+        Some(Input::PermissionDenied(value)) => {
+            lint_error(&format!("permission denied: {}", value.path))
+        }
+        None => return Err(missing("diagnostics")),
+    };
+    Ok(pb::ReadLintsToolResult {
+        result: Some(result),
+    })
+}
+
+fn lint_error(message: &str) -> pb::read_lints_tool_result::Result {
+    pb::read_lints_tool_result::Result::Error(pb::ReadLintsToolError {
+        error_message: message.into(),
+    })
+}
+
+pub(super) fn mcp(result: &pb::McpResult) -> Result<pb::McpToolResult> {
+    use pb::{mcp_result::Result as Input, mcp_tool_result::Result as Output};
+    let result = match result.result.as_ref() {
+        Some(Input::Success(value)) => Output::Success(value.clone()),
+        Some(Input::Error(value)) => mcp_error(&value.error),
+        Some(Input::Rejected(value)) => Output::Rejected(value.clone()),
+        Some(Input::PermissionDenied(value)) => Output::PermissionDenied(value.clone()),
+        Some(Input::ToolNotFound(value)) => {
+            mcp_error(&format!("MCP tool not found: {}", value.name))
+        }
+        Some(Input::ServerNotFound(value)) => {
+            mcp_error(&format!("MCP server not found: {}", value.name))
+        }
+        Some(Input::Approved(_)) => {
+            return Err(Error::Protocol("MCP approval is not terminal".into()))
+        }
+        None => return Err(missing("MCP")),
+    };
+    Ok(pb::McpToolResult {
+        result: Some(result),
+    })
+}
+
+fn mcp_error(message: &str) -> pb::mcp_tool_result::Result {
+    pb::mcp_tool_result::Result::Error(pb::McpToolError {
+        error: message.into(),
+        read_tool_def_reminder: String::new(),
+    })
+}
+
+pub(super) fn task(result: &pb::SubagentResult) -> Result<pb::TaskResult> {
+    use pb::{subagent_result::Result as Input, task_result::Result as Output};
+    let result = match result.result.as_ref() {
+        Some(Input::Success(value)) => Output::Success(pb::TaskSuccess {
+            agent_id: Some(value.agent_id.clone()),
+            result_suffix: value.final_message.clone(),
+            background_reason: value.background_reason,
+            transcript_path: value.transcript_path.clone(),
+            ..Default::default()
+        }),
+        Some(Input::Error(value)) => Output::Error(pb::TaskError {
+            error: value.error.clone(),
+        }),
+        None => return Err(missing("subagent")),
+    };
+    Ok(pb::TaskResult {
+        result: Some(result),
+    })
+}
+
+pub(super) fn glob(result: &pb::GrepResult) -> Result<pb::GlobToolResult> {
+    use pb::{glob_tool_result::Result as Output, grep_result::Result as Input};
+    let result = match result.result.as_ref() {
+        Some(Input::Success(success)) => {
+            let files = success
+                .active_editor_result
+                .iter()
+                .chain(success.workspace_results.values())
+                .find_map(|result| match result.result.as_ref() {
+                    Some(pb::grep_union_result::Result::Files(files)) => Some(files),
+                    _ => None,
+                });
+            Output::Success(pb::GlobToolSuccess {
+                pattern: success.pattern.clone(),
+                path: success.path.clone(),
+                files: files.map(|value| value.files.clone()).unwrap_or_default(),
+                total_files: files.map_or(0, |value| value.total_files),
+                client_truncated: files.is_some_and(|value| value.client_truncated),
+                ripgrep_truncated: files.is_some_and(|value| value.ripgrep_truncated),
+            })
+        }
+        Some(Input::Error(value)) => Output::Error(pb::GlobToolError {
+            error: value.error.clone(),
+        }),
+        None => return Err(missing("glob")),
+    };
+    Ok(pb::GlobToolResult {
+        result: Some(result),
+    })
+}
+
+pub(super) fn web_fetch(value: &pb::FetchResult) -> Result<pb::WebFetchResult> {
+    let result = match value.result.as_ref().ok_or_else(|| missing("WebFetch"))? {
+        pb::fetch_result::Result::Success(success) => {
+            pb::web_fetch_result::Result::Success(pb::WebFetchSuccess {
+                url: success.url.clone(),
+                markdown: success.content.clone(),
+                output_location: None,
+            })
+        }
+        pb::fetch_result::Result::Error(error) => {
+            pb::web_fetch_result::Result::Error(pb::WebFetchError {
+                url: error.url.clone(),
+                error: error.error.clone(),
+            })
+        }
+    };
+    Ok(pb::WebFetchResult {
+        result: Some(result),
+    })
+}
+
+fn missing(name: &str) -> Error {
+    Error::Protocol(format!("{name} returned no result"))
+}

cursor-server/src/cursor/tools/result/interaction.rs

@@ -0,0 +1,195 @@
+use crate::{
+    cursor::{interaction, proto::agent::v1 as pb},
+    Error, Result,
+};
+
+use super::ToolCompletion;
+use crate::cursor::tools::runtime::PendingInteraction;
+
+pub(crate) fn from_interaction(
+    pending: PendingInteraction,
+    response: &pb::InteractionResponse,
+) -> Result<ToolCompletion> {
+    use pb::{interaction_response::Result as Response, tool_call::Tool};
+    let call = &pending.call;
+    let mut rendered = interaction::render_tool_call(call, false)?;
+    let (output, is_error) = match (rendered.tool.as_mut(), response.result.as_ref()) {
+        (
+            Some(Tool::AskQuestionToolCall(tool)),
+            Some(Response::AskQuestionInteractionResponse(value)),
+        ) => {
+            let result = value
+                .result
+                .clone()
+                .ok_or_else(|| missing("ask question"))?;
+            let output = ask_output(&result)?;
+            tool.result = Some(result);
+            output
+        }
+        (
+            Some(Tool::CreatePlanToolCall(tool)),
+            Some(Response::CreatePlanRequestResponse(value)),
+        ) => {
+            let result = value.result.clone().ok_or_else(|| missing("create plan"))?;
+            let output = create_plan_output(&result)?;
+            tool.result = Some(result);
+            output
+        }
+        (
+            Some(Tool::SwitchModeToolCall(tool)),
+            Some(Response::SwitchModeRequestResponse(value)),
+        ) => {
+            let (result, output) = switch_mode_result(value)?;
+            tool.result = Some(result);
+            output
+        }
+        (Some(Tool::WebSearchToolCall(tool)), Some(Response::WebSearchRequestResponse(value))) => {
+            match value
+                .result
+                .as_ref()
+                .ok_or_else(|| missing("web search approval"))?
+            {
+                pb::web_search_request_response::Result::Rejected(rejected) => {
+                    tool.result = Some(pb::WebSearchResult {
+                        result: Some(pb::web_search_result::Result::Rejected(
+                            pb::WebSearchRejected {
+                                reason: rejected.reason.clone(),
+                            },
+                        )),
+                    });
+                    (rejected.reason.clone(), true)
+                }
+                pb::web_search_request_response::Result::Approved(_) => {
+                    return Err(Error::Provider(
+                        "WebSearch requires a configured server-side search executor".into(),
+                    ));
+                }
+            }
+        }
+        (Some(Tool::WebFetchToolCall(tool)), Some(Response::WebFetchRequestResponse(value))) => {
+            match value
+                .result
+                .as_ref()
+                .ok_or_else(|| missing("web fetch approval"))?
+            {
+                pb::web_fetch_request_response::Result::Rejected(rejected) => {
+                    tool.result = Some(pb::WebFetchResult {
+                        result: Some(pb::web_fetch_result::Result::Rejected(
+                            pb::WebFetchRejected {
+                                reason: rejected.reason.clone(),
+                            },
+                        )),
+                    });
+                    (rejected.reason.clone(), true)
+                }
+                pb::web_fetch_request_response::Result::Approved(_) => {
+                    return Err(Error::Protocol(
+                        "WebFetch approval is not a terminal tool result".into(),
+                    ));
+                }
+            }
+        }
+        (
+            Some(Tool::GenerateImageToolCall(tool)),
+            Some(Response::GenerateImageRequestResponse(value)),
+        ) => match value
+            .result
+            .as_ref()
+            .ok_or_else(|| missing("generate image approval"))?
+        {
+            pb::generate_image_request_response::Result::Rejected(rejected) => {
+                tool.result = Some(pb::GenerateImageResult {
+                    result: Some(pb::generate_image_result::Result::Error(
+                        pb::GenerateImageError {
+                            error: rejected.reason.clone(),
+                        },
+                    )),
+                });
+                (rejected.reason.clone(), true)
+            }
+            pb::generate_image_request_response::Result::Approved(_) => {
+                return Err(Error::Provider(
+                    "GenerateImage requires a configured server-side image executor".into(),
+                ));
+            }
+        },
+        _ => {
+            return Err(Error::Protocol(format!(
+                "unexpected InteractionResponse for tool {}",
+                call.name
+            )));
+        }
+    };
+    ToolCompletion::from_rendered(call, pending.started_at_ms, output, is_error, rendered)
+}
+
+fn ask_output(value: &pb::AskQuestionResult) -> Result<(String, bool)> {
+    use pb::ask_question_result::Result as R;
+    match value
+        .result
+        .as_ref()
+        .ok_or_else(|| missing("ask question"))?
+    {
+        R::Success(value) => Ok((
+            value
+                .answers
+                .iter()
+                .map(|answer| {
+                    let value = if answer.freeform_text.is_empty() {
+                        answer.selected_option_ids.join(", ")
+                    } else {
+                        answer.freeform_text.clone()
+                    };
+                    format!("{}: {value}", answer.question_id)
+                })
+                .collect::<Vec<_>>()
+                .join("\n"),
+            false,
+        )),
+        R::Error(value) => Ok((value.error_message.clone(), true)),
+        R::Rejected(value) => Ok((value.reason.clone(), true)),
+        R::Async(_) => Ok(("question is running asynchronously".into(), false)),
+    }
+}
+
+fn create_plan_output(value: &pb::CreatePlanResult) -> Result<(String, bool)> {
+    use pb::create_plan_result::Result as R;
+    match value
+        .result
+        .as_ref()
+        .ok_or_else(|| missing("create plan"))?
+    {
+        R::Success(_) => Ok((format!("plan created: {}", value.plan_uri), false)),
+        R::Error(value) => Ok((value.error.clone(), true)),
+    }
+}
+
+fn switch_mode_result(
+    value: &pb::SwitchModeRequestResponse,
+) -> Result<(pb::SwitchModeResult, (String, bool))> {
+    use pb::{switch_mode_request_response::Result as Input, switch_mode_result::Result as Output};
+    match value
+        .result
+        .as_ref()
+        .ok_or_else(|| missing("switch mode"))?
+    {
+        Input::Approved(_) => Ok((
+            pb::SwitchModeResult {
+                result: Some(Output::Success(pb::SwitchModeSuccess::default())),
+            },
+            ("mode switched".into(), false),
+        )),
+        Input::Rejected(value) => Ok((
+            pb::SwitchModeResult {
+                result: Some(Output::Rejected(pb::SwitchModeRejected {
+                    reason: value.reason.clone(),
+                })),
+            },
+            (value.reason.clone(), true),
+        )),
+    }
+}
+
+fn missing(name: &str) -> Error {
+    Error::Protocol(format!("{name} returned no result"))
+}

cursor-server/src/cursor/tools/result/local.rs

@@ -0,0 +1,147 @@
+use serde_json::Value;
+
+use crate::{
+    cursor::{interaction, proto::agent::v1 as pb},
+    model::{ToolCall, ToolResult},
+    Error, Result,
+};
+
+use super::{now_ms, ToolCompletion};
+
+pub(crate) fn local(call: &ToolCall, message_index: usize) -> Result<ToolCompletion> {
+    match normalized(&call.name).as_str() {
+        "todowrite" => todo_write(call),
+        "updatecurrentstep" => update_current_step(call, message_index),
+        _ => Err(Error::Protocol(format!("unsupported tool: {}", call.name))),
+    }
+}
+
+fn todo_write(call: &ToolCall) -> Result<ToolCompletion> {
+    let todos = todo_items(&call.arguments);
+    let total_count = todos.len() as i32;
+    let was_merge = call
+        .arguments
+        .get("merge")
+        .and_then(Value::as_bool)
+        .unwrap_or(false);
+    let mut rendered = interaction::render_tool_call(call, false)?;
+    let Some(pb::tool_call::Tool::UpdateTodosToolCall(tool)) = rendered.tool.as_mut() else {
+        return Err(Error::Protocol(
+            "TodoWrite has no Cursor representation".into(),
+        ));
+    };
+    tool.result = Some(pb::UpdateTodosResult {
+        result: Some(pb::update_todos_result::Result::Success(
+            pb::UpdateTodosSuccess {
+                todos,
+                total_count,
+                was_merge,
+            },
+        )),
+    });
+    let tool = rendered
+        .tool
+        .ok_or_else(|| Error::Protocol("TodoWrite has no Cursor representation".into()))?;
+    Ok(ToolCompletion::new(
+        call,
+        now_ms(),
+        ToolResult {
+            call_id: call.call_id.clone(),
+            content: call.arguments.to_string(),
+            is_error: false,
+        },
+        tool,
+    ))
+}
+
+fn update_current_step(call: &ToolCall, message_index: usize) -> Result<ToolCompletion> {
+    let current_step = call
+        .arguments
+        .get("current_step")
+        .and_then(Value::as_str)
+        .unwrap_or_default()
+        .to_string();
+    let mut rendered = interaction::render_tool_call(call, false)?;
+    let Some(pb::tool_call::Tool::CommunicateUpdateToolCall(tool)) = rendered.tool.as_mut() else {
+        return Err(Error::Protocol(
+            "UpdateCurrentStep has no Cursor representation".into(),
+        ));
+    };
+    let message_index = u32::try_from(message_index)
+        .map_err(|_| Error::Protocol("Cursor message index space exhausted".into()))?;
+    tool.result = Some(pb::CommunicateUpdateResult {
+        result: Some(pb::communicate_update_result::Result::Success(
+            pb::CommunicateUpdateSuccess {
+                current_step: current_step.clone(),
+                message_index,
+            },
+        )),
+    });
+    let tool = rendered
+        .tool
+        .ok_or_else(|| Error::Protocol("UpdateCurrentStep has no Cursor representation".into()))?;
+    Ok(ToolCompletion::new(
+        call,
+        now_ms(),
+        ToolResult {
+            call_id: call.call_id.clone(),
+            content: serde_json::json!({
+                "success": {
+                    "current_step": current_step,
+                    "message_index": message_index,
+                }
+            })
+            .to_string(),
+            is_error: false,
+        },
+        tool,
+    ))
+}
+
+pub(crate) fn todo_items(arguments: &Value) -> Vec<pb::TodoItem> {
+    arguments
+        .get("todos")
+        .and_then(Value::as_array)
+        .into_iter()
+        .flatten()
+        .map(|todo| pb::TodoItem {
+            id: text(todo, "id"),
+            content: text(todo, "content"),
+            status: match todo
+                .get("status")
+                .and_then(Value::as_str)
+                .unwrap_or("pending")
+            {
+                "in_progress" => pb::TodoStatus::InProgress as i32,
+                "completed" => pb::TodoStatus::Completed as i32,
+                "cancelled" => pb::TodoStatus::Cancelled as i32,
+                _ => pb::TodoStatus::Pending as i32,
+            },
+            created_at: 0,
+            updated_at: 0,
+            dependencies: todo
+                .get("dependencies")
+                .and_then(Value::as_array)
+                .into_iter()
+                .flatten()
+                .filter_map(Value::as_str)
+                .map(str::to_string)
+                .collect(),
+        })
+        .collect()
+}
+
+fn text(value: &Value, name: &str) -> String {
+    value
+        .get(name)
+        .and_then(Value::as_str)
+        .unwrap_or_default()
+        .into()
+}
+
+fn normalized(name: &str) -> String {
+    name.chars()
+        .filter(|character| character.is_ascii_alphanumeric())
+        .flat_map(char::to_lowercase)
+        .collect()
+}

cursor-server/src/cursor/tools/result/mcp_state.rs

@@ -0,0 +1,114 @@
+use serde_json::Value;
+
+use crate::{cursor::proto::agent::v1 as pb, model::ToolResult, Error, Result};
+
+use super::{prost_json, ToolCompletion};
+use crate::cursor::tools::runtime::PendingExec;
+
+pub(super) fn complete(
+    pending: PendingExec,
+    result: &pb::McpStateExecResult,
+) -> Result<ToolCompletion> {
+    let call = &pending.call;
+    let server_filter = call.arguments.get("server").and_then(Value::as_str);
+    let tool_filter = call.arguments.get("toolName").and_then(Value::as_str);
+    if tool_filter.is_some() && server_filter.is_none() {
+        return Err(Error::Protocol(
+            "GetMcpTools toolName requires server".into(),
+        ));
+    }
+    let pattern = call
+        .arguments
+        .get("pattern")
+        .and_then(Value::as_str)
+        .map(regex::Regex::new)
+        .transpose()
+        .map_err(|error| Error::Protocol(format!("invalid GetMcpTools pattern: {error}")))?;
+    let args = pb::GetMcpToolsArgs {
+        server: server_filter.map(str::to_string),
+        tool_name: tool_filter.map(str::to_string),
+        pattern: call
+            .arguments
+            .get("pattern")
+            .and_then(Value::as_str)
+            .map(str::to_string),
+        tool_call_id: call.call_id.clone(),
+    };
+    let (content, is_error, result) = match result
+        .result
+        .as_ref()
+        .ok_or_else(|| Error::Protocol("McpStateExecResult is missing result".into()))?
+    {
+        pb::mcp_state_exec_result::Result::Success(success) => {
+            let matches = success
+                .servers
+                .iter()
+                .filter(|server| {
+                    server_filter.is_none_or(|value| value == server.server_identifier)
+                })
+                .flat_map(|server| {
+                    server.tools.iter().filter_map(|tool| {
+                        if tool_filter.is_some_and(|value| value != tool.tool_name)
+                            || pattern.as_ref().is_some_and(|pattern| {
+                                !pattern.is_match(&server.server_identifier)
+                                    && !pattern.is_match(&tool.tool_name)
+                            })
+                        {
+                            return None;
+                        }
+                        Some(serde_json::json!({
+                            "server": server.server_identifier,
+                            "toolName": tool.tool_name,
+                            "description": tool.description,
+                            "inputSchema": schema(tool),
+                        }))
+                    })
+                })
+                .collect::<Vec<_>>();
+            let content = serde_json::to_string_pretty(&matches)?;
+            let wire = pb::get_mcp_tools_agent_result::Result::Success(pb::GetMcpToolsSuccess {
+                content: content.clone(),
+                output_file_path: None,
+            });
+            (content, false, wire)
+        }
+        pb::mcp_state_exec_result::Result::Error(error) => failure(&error.error),
+        pb::mcp_state_exec_result::Result::Rejected(rejected) => failure(&rejected.reason),
+    };
+    Ok(ToolCompletion::new(
+        call,
+        pending.started_at_ms,
+        ToolResult {
+            call_id: call.call_id.clone(),
+            content,
+            is_error,
+        },
+        pb::tool_call::Tool::GetMcpToolsToolCall(pb::GetMcpToolsToolCall {
+            args: Some(args),
+            result: Some(pb::GetMcpToolsAgentResult {
+                result: Some(result),
+            }),
+        }),
+    ))
+}
+
+fn failure(message: &str) -> (String, bool, pb::get_mcp_tools_agent_result::Result) {
+    (
+        message.into(),
+        true,
+        pb::get_mcp_tools_agent_result::Result::Error(pb::GetMcpToolsError {
+            error: message.into(),
+        }),
+    )
+}
+
+fn schema(tool: &pb::McpToolDefinition) -> Value {
+    let raw = tool.input_schema_json.clone().unwrap_or_else(|| {
+        tool.input_schema
+            .as_ref()
+            .map(prost_json)
+            .and_then(|value| serde_json::to_string(&value).ok())
+            .unwrap_or_else(|| "{}".into())
+    });
+    serde_json::from_str(&raw).unwrap_or(Value::String(raw))
+}

cursor-server/src/cursor/tools/result/mod.rs

@@ -0,0 +1,122 @@
+mod await_shell;
+mod exec;
+mod interaction;
+mod local;
+mod mcp_state;
+
+use serde_json::Value;
+use tokio::sync::mpsc;
+
+use crate::{
+    cursor::proto::agent::v1 as pb,
+    model::{ToolCall, ToolResult},
+    Error, Result,
+};
+
+use super::runtime::now_ms;
+
+pub(crate) use await_shell::{await_error, await_result, await_sleep};
+pub(crate) use exec::{edit_failure, from_exec};
+pub(crate) use interaction::from_interaction;
+pub(crate) use local::{local, todo_items};
+
+#[derive(Clone, Debug)]
+pub struct ToolCompletion {
+    result: ToolResult,
+    tool_call: pb::ToolCall,
+}
+
+impl ToolCompletion {
+    pub fn result(&self) -> &ToolResult {
+        &self.result
+    }
+
+    pub fn tool_call(&self) -> &pb::ToolCall {
+        &self.tool_call
+    }
+
+    pub(super) fn new(
+        call: &ToolCall,
+        started_at_ms: u64,
+        result: ToolResult,
+        tool: pb::tool_call::Tool,
+    ) -> Self {
+        Self {
+            result,
+            tool_call: pb::ToolCall {
+                tool_call_id: Some(call.call_id.clone()),
+                started_at_ms: Some(started_at_ms),
+                completed_at_ms: Some(now_ms()),
+                tool: Some(tool),
+                hook_additional_contexts: Vec::new(),
+            },
+        }
+    }
+
+    pub(super) fn from_rendered(
+        call: &ToolCall,
+        started_at_ms: u64,
+        output: String,
+        is_error: bool,
+        rendered: pb::ToolCall,
+    ) -> Result<Self> {
+        let tool = rendered.tool.ok_or_else(|| {
+            Error::Protocol(format!("tool {} has no Cursor representation", call.name))
+        })?;
+        Ok(Self::new(
+            call,
+            started_at_ms,
+            ToolResult {
+                call_id: call.call_id.clone(),
+                content: output,
+                is_error,
+            },
+            tool,
+        ))
+    }
+}
+
+#[derive(Clone)]
+pub struct ToolResultSender(mpsc::UnboundedSender<Result<ToolCompletion>>);
+pub struct ToolResultReceiver(mpsc::UnboundedReceiver<Result<ToolCompletion>>);
+
+pub fn tool_result_channel() -> (ToolResultSender, ToolResultReceiver) {
+    let (sender, receiver) = mpsc::unbounded_channel();
+    (ToolResultSender(sender), ToolResultReceiver(receiver))
+}
+
+impl ToolResultSender {
+    pub fn send(&self, result: ToolCompletion) {
+        let _ = self.0.send(Ok(result));
+    }
+
+    pub fn send_error(&self, error: Error) {
+        let _ = self.0.send(Err(error));
+    }
+}
+
+impl ToolResultReceiver {
+    pub async fn recv(&mut self) -> Option<Result<ToolCompletion>> {
+        self.0.recv().await
+    }
+}
+
+pub(super) fn prost_json(value: &prost_types::Value) -> Value {
+    use prost_types::value::Kind;
+    match value.kind.as_ref() {
+        None | Some(Kind::NullValue(_)) => Value::Null,
+        Some(Kind::NumberValue(value)) => serde_json::Number::from_f64(*value)
+            .map(Value::Number)
+            .unwrap_or(Value::Null),
+        Some(Kind::StringValue(value)) => Value::String(value.clone()),
+        Some(Kind::BoolValue(value)) => Value::Bool(*value),
+        Some(Kind::StructValue(value)) => Value::Object(
+            value
+                .fields
+                .iter()
+                .map(|(key, value)| (key.clone(), prost_json(value)))
+                .collect(),
+        ),
+        Some(Kind::ListValue(value)) => Value::Array(value.values.iter().map(prost_json).collect()),
+    }
+}

cursor-server/src/cursor/tools/runtime.rs

@@ -0,0 +1,313 @@
+use std::{
+    collections::HashMap,
+    sync::{
+        atomic::{AtomicU32, Ordering},
+        Arc,
+    },
+    time::Instant,
+};
+
+use tokio::sync::Mutex;
+
+use crate::{cursor::proto::agent::v1 as pb, model::ToolCall, Error, Result};
+
+use super::edit::EditWrite;
+
+#[derive(Clone, Default)]
+pub struct CursorToolRuntime {
+    next_id: Arc<AtomicU32>,
+    execs: Arc<Mutex<HashMap<u32, PendingExec>>>,
+    interactions: Arc<Mutex<HashMap<u32, PendingInteraction>>>,
+    completed: Arc<Mutex<HashMap<u32, String>>>,
+    mcp_tools: Arc<Mutex<HashMap<(String, String), pb::McpToolDefinition>>>,
+}
+
+pub(crate) struct PendingExec {
+    pub call: ToolCall,
+    pub context: ExecContext,
+    pub started_at_ms: u64,
+    pub stdout: String,
+    pub stderr: String,
+    pub stage: ExecStage,
+}
+
+pub(crate) enum ExecStage {
+    Direct,
+    EditRead,
+    EditWrite(EditWrite),
+    Await(AwaitState),
+}
+
+pub(crate) struct AwaitState {
+    pub deadline: Instant,
+    pub output_file_path: String,
+    pub task_id: String,
+    pub regex: Option<String>,
+}
+
+#[derive(Clone, Debug, Default)]
+pub struct ExecContext {
+    pub conversation_id: String,
+    pub root_conversation_id: String,
+    pub model_id: String,
+    pub subagent_models: HashMap<String, SubagentModel>,
+    pub terminals_folder: String,
+    pub admin_command_denylist: Vec<String>,
+}
+
+#[derive(Clone, Debug)]
+pub enum SubagentModel {
+    Model(String),
+    Disabled,
+}
+
+pub(crate) struct PendingInteraction {
+    pub call: ToolCall,
+    pub context: ExecContext,
+    pub started_at_ms: u64,
+}
+
+impl CursorToolRuntime {
+    pub async fn reserve_exec(&self, call: &ToolCall, context: &ExecContext) -> Result<u32> {
+        self.reserve_exec_stage(call, context, ExecStage::Direct, None)
+            .await
+    }
+
+    pub(crate) async fn reserve_edit_read(
+        &self,
+        call: &ToolCall,
+        context: &ExecContext,
+    ) -> Result<u32> {
+        self.reserve_exec_stage(call, context, ExecStage::EditRead, None)
+            .await
+    }
+
+    pub(crate) async fn reserve_edit_write(
+        &self,
+        call: &ToolCall,
+        context: &ExecContext,
+        write: EditWrite,
+        started_at_ms: u64,
+    ) -> Result<u32> {
+        self.reserve_exec_stage(
+            call,
+            context,
+            ExecStage::EditWrite(write),
+            Some(started_at_ms),
+        )
+        .await
+    }
+
+    pub(crate) async fn reserve_await(
+        &self,
+        call: &ToolCall,
+        context: &ExecContext,
+    ) -> Result<u32> {
+        let task_id = call
+            .arguments
+            .get("shell_id")
+            .and_then(serde_json::Value::as_str)
+            .ok_or_else(|| Error::Protocol("AwaitShell is missing shell_id".into()))?;
+        let block_ms = call
+            .arguments
+            .get("block_until_ms")
+            .and_then(serde_json::Value::as_u64)
+            .unwrap_or(30_000);
+        if block_ms > 7_140_000 {
+            return Err(Error::Protocol(
+                "AwaitShell block_until_ms exceeds 7140000".into(),
+            ));
+        }
+        let output_file_path = format!(
+            "{}/{}.txt",
+            context.terminals_folder.trim_end_matches('/'),
+            task_id
+        );
+        self.reserve_exec_stage(
+            call,
+            context,
+            ExecStage::Await(AwaitState {
+                deadline: Instant::now() + std::time::Duration::from_millis(block_ms),
+                output_file_path,
+                task_id: task_id.to_string(),
+                regex: call
+                    .arguments
+                    .get("pattern")
+                    .and_then(serde_json::Value::as_str)
+                    .map(str::to_string),
+            }),
+            None,
+        )
+        .await
+    }
+
+    pub(crate) async fn reserve_await_again(
+        &self,
+        call: &ToolCall,
+        context: &ExecContext,
+        state: AwaitState,
+        started_at_ms: u64,
+    ) -> Result<u32> {
+        self.reserve_exec_stage(call, context, ExecStage::Await(state), Some(started_at_ms))
+            .await
+    }
+
+    async fn reserve_exec_stage(
+        &self,
+        call: &ToolCall,
+        context: &ExecContext,
+        stage: ExecStage,
+        started_at_ms: Option<u64>,
+    ) -> Result<u32> {
+        let id = self.next_id()?;
+        self.execs.lock().await.insert(
+            id,
+            PendingExec {
+                call: call.clone(),
+                context: context.clone(),
+                started_at_ms: started_at_ms.unwrap_or_else(now_ms),
+                stdout: String::new(),
+                stderr: String::new(),
+                stage,
+            },
+        );
+        Ok(id)
+    }
+
+    pub async fn reserve_interaction(&self, call: &ToolCall, context: &ExecContext) -> Result<u32> {
+        let id = self.next_id()?;
+        self.interactions.lock().await.insert(
+            id,
+            PendingInteraction {
+                call: call.clone(),
+                context: context.clone(),
+                started_at_ms: now_ms(),
+            },
+        );
+        Ok(id)
+    }
+
+    pub async fn exec_call(&self, id: u32) -> Option<ToolCall> {
+        self.execs
+            .lock()
+            .await
+            .get(&id)
+            .map(|entry| entry.call.clone())
+    }
+
+    pub async fn append_stdout(&self, id: u32, data: &str) -> bool {
+        let mut entries = self.execs.lock().await;
+        let Some(entry) = entries.get_mut(&id) else {
+            return false;
+        };
+        entry.stdout.push_str(data);
+        true
+    }
+
+    pub async fn append_stderr(&self, id: u32, data: &str) -> bool {
+        let mut entries = self.execs.lock().await;
+        let Some(entry) = entries.get_mut(&id) else {
+            return false;
+        };
+        entry.stderr.push_str(data);
+        true
+    }
+
+    pub(crate) async fn take_exec(&self, id: u32) -> Option<PendingExec> {
+        let pending = self.execs.lock().await.remove(&id);
+        if let Some(pending) = &pending {
+            self.completed
+                .lock()
+                .await
+                .insert(id, pending.call.call_id.clone());
+        }
+        pending
+    }
+
+    pub(crate) async fn take_interaction(&self, id: u32) -> Option<PendingInteraction> {
+        let pending = self.interactions.lock().await.remove(&id);
+        if let Some(pending) = &pending {
+            self.completed
+                .lock()
+                .await
+                .insert(id, pending.call.call_id.clone());
+        }
+        pending
+    }
+
+    pub async fn completed_call(&self, id: u32) -> Option<String> {
+        self.completed.lock().await.get(&id).cloned()
+    }
+
+    pub(crate) async fn remember_mcp_state(
+        &self,
+        call: &ToolCall,
+        result: &pb::McpStateExecResult,
+    ) {
+        let Some(pb::mcp_state_exec_result::Result::Success(success)) = result.result.as_ref()
+        else {
+            return;
+        };
+        let server_filter = call
+            .arguments
+            .get("server")
+            .and_then(serde_json::Value::as_str);
+        let mut tools = self.mcp_tools.lock().await;
+        match server_filter {
+            Some(server) => tools.retain(|(known_server, _), _| known_server != server),
+            None => tools.clear(),
+        }
+        for server in &success.servers {
+            for tool in &server.tools {
+                tools.insert(
+                    (server.server_identifier.clone(), tool.tool_name.clone()),
+                    tool.clone(),
+                );
+            }
+        }
+    }
+
+    pub(crate) async fn mcp_tool(&self, server: &str, tool: &str) -> Option<pb::McpToolDefinition> {
+        self.mcp_tools
+            .lock()
+            .await
+            .get(&(server.to_string(), tool.to_string()))
+            .cloned()
+    }
+
+    pub async fn clear_completed(&self) {
+        self.completed.lock().await.clear();
+    }
+
+    pub async fn discard_exec(&self, id: u32) {
+        self.execs.lock().await.remove(&id);
+    }
+
+    pub async fn discard_interaction(&self, id: u32) {
+        self.interactions.lock().await.remove(&id);
+    }
+
+    pub async fn drain_running(&self) -> Vec<u32> {
+        let mut entries = self.execs.lock().await;
+        let mut ids = entries.drain().map(|(id, _)| id).collect::<Vec<_>>();
+        ids.sort_unstable();
+        self.interactions.lock().await.clear();
+        self.completed.lock().await.clear();
+        self.mcp_tools.lock().await.clear();
+        ids
+    }
+
+    fn next_id(&self) -> Result<u32> {
+        self.next_id
+            .fetch_add(1, Ordering::Relaxed)
+            .checked_add(1)
+            .ok_or_else(|| Error::Protocol("Cursor message id space exhausted".into()))
+    }
+}
+
+pub(crate) fn now_ms() -> u64 {
+    std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_millis() as u64
+}

cursor-server/src/cursor/tools/stream.rs

@@ -0,0 +1,255 @@
+use crate::{
+    cursor::{
+        interaction,
+        json_stream::{JsonStringFields, StringFieldEvent},
+        proto::agent::v1 as pb,
+    },
+    model::ToolCall,
+    Result,
+};
+
+pub struct ToolCallStream {
+    presentation: Presentation,
+}
+
+enum Presentation {
+    Plain,
+    Edit(EditProjection),
+}
+
+struct EditProjection {
+    fields: JsonStringFields,
+    path_field: &'static str,
+    content_field: &'static str,
+    path: String,
+    content: NewlineStream,
+}
+
+impl ToolCallStream {
+    pub fn new(name: &str) -> Self {
+        let presentation = match normalized(name).as_str() {
+            "write" => Presentation::Edit(EditProjection::new("path", "contents")),
+            "strreplace" => Presentation::Edit(EditProjection::new("path", "new_string")),
+            "editnotebook" => {
+                Presentation::Edit(EditProjection::new("target_notebook", "new_string"))
+            }
+            _ => Presentation::Plain,
+        };
+        Self { presentation }
+    }
+
+    pub fn arguments_delta(
+        &mut self,
+        call: &ToolCall,
+        raw_delta: &str,
+    ) -> Result<Vec<pb::AgentServerMessage>> {
+        match &mut self.presentation {
+            Presentation::Plain => Ok(vec![interaction::arguments_delta(call, raw_delta)?]),
+            Presentation::Edit(edit) => {
+                let mut messages = Vec::new();
+                edit.project(call, raw_delta, &mut messages)?;
+                Ok(messages)
+            }
+        }
+    }
+}
+
+impl EditProjection {
+    fn new(path_field: &'static str, content_field: &'static str) -> Self {
+        Self {
+            fields: JsonStringFields::default(),
+            path_field,
+            content_field,
+            path: String::new(),
+            content: NewlineStream::default(),
+        }
+    }
+
+    fn project(
+        &mut self,
+        call: &ToolCall,
+        raw_delta: &str,
+        messages: &mut Vec<pb::AgentServerMessage>,
+    ) -> Result<()> {
+        for event in self.fields.push(raw_delta)? {
+            match event {
+                StringFieldEvent::Delta { name, text } if name == self.path_field => {
+                    self.path.push_str(&text)
+                }
+                StringFieldEvent::End { name } if name == self.path_field => {
+                    messages.push(interaction::edit_path_partial(call, &self.path));
+                }
+                StringFieldEvent::Delta { name, text } if name == self.content_field => {
+                    let content = self.content.push(&text, false);
+                    if !content.is_empty() {
+                        messages.push(interaction::edit_content_delta(call, content));
+                    }
+                }
+                StringFieldEvent::End { name } if name == self.content_field => {
+                    let content = self.content.push("", true);
+                    if !content.is_empty() {
+                        messages.push(interaction::edit_content_delta(call, content));
+                    }
+                }
+                _ => {}
+            }
+        }
+        Ok(())
+    }
+}
+
+#[derive(Default)]
+struct NewlineStream {
+    pending_cr: bool,
+}
+
+impl NewlineStream {
+    fn push(&mut self, text: &str, finished: bool) -> String {
+        let mut output = String::with_capacity(text.len());
+        for character in text.chars() {
+            if self.pending_cr {
+                output.push('\n');
+                self.pending_cr = false;
+                if character == '\n' {
+                    continue;
+                }
+            }
+            if character == '\r' {
+                self.pending_cr = true;
+            } else {
+                output.push(character);
+            }
+        }
+        if finished && self.pending_cr {
+            output.push('\n');
+            self.pending_cr = false;
+        }
+        output
+    }
+}
+
+fn normalized(value: &str) -> String {
+    value
+        .chars()
+        .filter(|character| character.is_ascii_alphanumeric())
+        .flat_map(char::to_lowercase)
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use serde_json::{json, Value};
+
+    use super::*;
+
+    fn call(name: &str) -> ToolCall {
+        ToolCall {
+            index: 0,
+            call_id: "call-1".into(),
+            model_call_id: "model-1".into(),
+            name: name.into(),
+            arguments_text: String::new(),
+            arguments: Value::Null,
+        }
+    }
+
+    #[test]
+    fn plain_tools_only_project_raw_argument_deltas() {
+        let call = call("Read");
+        let mut stream = ToolCallStream::new(&call.name);
+        assert_eq!(
+            stream.arguments_delta(&call, "{\"path\":").unwrap().len(),
+            1
+        );
+    }
+
+    #[test]
+    fn write_projects_path_and_content_without_starting_execution() {
+        let call = call("Write");
+        let mut stream = ToolCallStream::new(&call.name);
+        let first = stream
+            .arguments_delta(&call, "{\"path\":\"/tmp/a\",\"contents\":\"hel")
+            .unwrap();
+        assert_eq!(first.len(), 2);
+        assert!(matches!(
+            first[0].message,
+            Some(pb::agent_server_message::Message::InteractionUpdate(
+                pb::InteractionUpdate {
+                    message: Some(pb::interaction_update::Message::PartialToolCall(_))
+                }
+            ))
+        ));
+        assert_eq!(edit_delta(&first[1]), "hel");
+
+        let second = stream.arguments_delta(&call, "lo\\n世界\"}").unwrap();
+        assert_eq!(second.len(), 1);
+        assert_eq!(edit_delta(&second[0]), "lo\n世界");
+    }
+
+    #[test]
+    fn str_replace_projects_only_new_string_when_path_arrives_later() {
+        let mut call = call("StrReplace");
+        let mut stream = ToolCallStream::new(&call.name);
+        let first = stream
+            .arguments_delta(&call, "{\"new_string\":\"new\",\"old_string\":\"old\",")
+            .unwrap();
+        assert_eq!(first.len(), 1);
+        assert_eq!(edit_delta(&first[0]), "new");
+        let second = stream
+            .arguments_delta(&call, "\"path\":\"/tmp/a\"}")
+            .unwrap();
+        assert_eq!(second.len(), 1);
+        assert!(matches!(
+            second[0].message,
+            Some(pb::agent_server_message::Message::InteractionUpdate(
+                pb::InteractionUpdate {
+                    message: Some(pb::interaction_update::Message::PartialToolCall(_))
+                }
+            ))
+        ));
+
+        call.arguments = json!({
+            "path": "/tmp/a",
+            "old_string": "old",
+            "new_string": "new"
+        });
+        let rendered = interaction::render_tool_call(&call, false).unwrap();
+        let Some(pb::tool_call::Tool::EditToolCall(edit)) = rendered.tool else {
+            panic!("expected EditToolCall")
+        };
+        assert_eq!(edit.args.unwrap().stream_content.as_deref(), Some("new"));
+    }
+
+    #[test]
+    fn edit_stream_normalizes_split_crlf_once() {
+        let call = call("Write");
+        let mut stream = ToolCallStream::new(&call.name);
+        let first = stream
+            .arguments_delta(&call, "{\"contents\":\"a\\r")
+            .unwrap();
+        let second = stream
+            .arguments_delta(&call, "\\nb\\r\",\"path\":\"/tmp/a\"}")
+            .unwrap();
+        assert_eq!(edit_delta(&first[0]), "a");
+        assert_eq!(edit_delta(&second[0]), "\nb");
+        assert_eq!(edit_delta(&second[1]), "\n");
+    }
+
+    fn edit_delta(message: &pb::AgentServerMessage) -> &str {
+        let Some(pb::agent_server_message::Message::InteractionUpdate(update)) = &message.message
+        else {
+            panic!("expected InteractionUpdate")
+        };
+        let Some(pb::interaction_update::Message::ToolCallDelta(update)) = &update.message else {
+            panic!("expected ToolCallDelta")
+        };
+        let Some(pb::tool_call_delta::Delta::EditToolCallDelta(delta)) = update
+            .tool_call_delta
+            .as_deref()
+            .and_then(|delta| delta.delta.as_ref())
+        else {
+            panic!("expected EditToolCallDelta")
+        };
+        &delta.stream_content_delta
+    }
+}

cursor-server/src/cursor/usage.rs

@@ -0,0 +1,309 @@
+use std::collections::HashSet;
+
+use crate::{
+    cursor::proto::agent::v1 as pb,
+    model::{CanonicalMessage, ContentPart, MessageContent, Origin, ToolDefinition},
+    Result,
+};
+
+const CATEGORIES: [(&str, &str); 8] = [
+    ("system_prompt", "System prompt"),
+    ("tools", "Tool definitions"),
+    ("rules", "Rules"),
+    ("skills", "Skills"),
+    ("mcp", "MCP & dynamic tools"),
+    ("subagents", "Subagent definitions"),
+    ("summarized_conversation", "Summarized conversation"),
+    ("conversation", "Conversation"),
+];
+
+const SYSTEM: usize = 0;
+const TOOLS: usize = 1;
+const RULES: usize = 2;
+const SKILLS: usize = 3;
+const MCP: usize = 4;
+const SUBAGENTS: usize = 5;
+const SUMMARY: usize = 6;
+const CONVERSATION: usize = 7;
+
+#[derive(Clone, Copy, Default)]
+struct Measure {
+    characters: u64,
+    token_units: u64,
+}
+
+impl Measure {
+    fn add(&mut self, text: &str) {
+        self.characters += text.encode_utf16().count() as u64;
+        let mut units = 0_u64;
+        for character in text.chars() {
+            let width = character.len_utf16() as u64;
+            units += if character.is_ascii() {
+                width * 273
+            } else {
+                width * 550
+            };
+        }
+        self.token_units += units;
+    }
+
+    fn estimated_tokens(self) -> u64 {
+        self.token_units.div_ceil(1_000)
+    }
+}
+
+pub(crate) fn breakdown(
+    used_tokens: u32,
+    max_tokens: u32,
+    baseline: Option<&pb::PromptTokenBreakdownSnapshot>,
+    instructions: &str,
+    tools: &[ToolDefinition],
+    dynamic_tools: &HashSet<String>,
+    messages: &[CanonicalMessage],
+) -> Result<pb::PromptTokenBreakdownSnapshot> {
+    let mut measures = [Measure::default(); 8];
+    measures[SYSTEM].add(instructions);
+    for tool in tools {
+        let encoded = serde_json::to_string(tool)?;
+        if dynamic_tools.contains(&tool.name) {
+            measures[MCP].add(&encoded);
+        } else {
+            measures[TOOLS].add(&encoded);
+        }
+    }
+    for message in messages {
+        measure_message(message, &mut measures)?;
+    }
+
+    let mut estimates = [0_u64; 8];
+    for index in 0..CONVERSATION {
+        estimates[index] = measures[index].estimated_tokens();
+    }
+    if let Some(summary) = baseline.and_then(|snapshot| {
+        snapshot
+            .categories
+            .iter()
+            .find(|category| category.id == CATEGORIES[SUMMARY].0)
+    }) {
+        measures[SUMMARY].characters = summary.character_count.unwrap_or(0) as u64;
+        estimates[SUMMARY] = summary.estimated_tokens as u64;
+    }
+    fit_special_estimates(&mut estimates, used_tokens as u64);
+    estimates[CONVERSATION] =
+        (used_tokens as u64).saturating_sub(estimates[..CONVERSATION].iter().sum::<u64>());
+
+    let categories = CATEGORIES
+        .iter()
+        .enumerate()
+        .map(|(index, (id, label))| pb::PromptTokenBreakdownCategory {
+            id: (*id).into(),
+            label: (*label).into(),
+            estimated_tokens: estimates[index].min(u32::MAX as u64) as u32,
+            character_count: (measures[index].characters != 0)
+                .then_some(measures[index].characters.min(u32::MAX as u64) as u32),
+        })
+        .collect();
+    Ok(pb::PromptTokenBreakdownSnapshot {
+        total_used_tokens: used_tokens,
+        max_tokens,
+        categories,
+    })
+}
+
+fn measure_message(message: &CanonicalMessage, measures: &mut [Measure; 8]) -> Result<()> {
+    match &message.content {
+        MessageContent::Parts { parts } => {
+            for part in parts {
+                if let ContentPart::Text { text } = part {
+                    if message.origin == Origin::Runtime {
+                        measure_runtime(text, measures);
+                    } else {
+                        measures[CONVERSATION].add(text);
+                    }
+                }
+            }
+        }
+        MessageContent::Assistant {
+            text,
+            thinking,
+            tool_calls,
+            ..
+        } => {
+            measures[CONVERSATION].add(text);
+            measures[CONVERSATION].add(thinking);
+            measures[CONVERSATION].add(&serde_json::to_string(tool_calls)?);
+        }
+        MessageContent::ToolResult(result) => {
+            measures[CONVERSATION].add(&serde_json::to_string(result)?);
+        }
+    }
+    Ok(())
+}
+
+fn measure_runtime(text: &str, measures: &mut [Measure; 8]) {
+    let mut ranges = Vec::new();
+    collect_ranges(text, "rules", RULES, &mut ranges);
+    collect_ranges(text, "rule", RULES, &mut ranges);
+    collect_ranges(text, "agent_skills", SKILLS, &mut ranges);
+    collect_ranges(text, "skill", SKILLS, &mut ranges);
+    collect_ranges(text, "subagents", SUBAGENTS, &mut ranges);
+    collect_ranges(text, "mcp_meta_tools", MCP, &mut ranges);
+    ranges.sort_by_key(|range| range.0);
+
+    let mut cursor = 0;
+    for (start, end, category) in ranges {
+        if start < cursor {
+            continue;
+        }
+        measures[CONVERSATION].add(&text[cursor..start]);
+        measures[category].add(&text[start..end]);
+        cursor = end;
+    }
+    measures[CONVERSATION].add(&text[cursor..]);
+}
+
+fn collect_ranges(text: &str, tag: &str, category: usize, output: &mut Vec<(usize, usize, usize)>) {
+    let opening = format!("<{tag}");
+    let closing = format!("</{tag}>");
+    let mut cursor = 0;
+    while let Some(relative_start) = text[cursor..].find(&opening) {
+        let start = cursor + relative_start;
+        let Some(open_end) = text[start..].find('>').map(|offset| start + offset + 1) else {
+            break;
+        };
+        let Some(relative_end) = text[open_end..].find(&closing) else {
+            break;
+        };
+        let end = open_end + relative_end + closing.len();
+        output.push((start, end, category));
+        cursor = end;
+    }
+}
+
+fn fit_special_estimates(estimates: &mut [u64; 8], total: u64) {
+    let special_total = estimates[..CONVERSATION].iter().sum::<u64>();
+    if special_total <= total || special_total == 0 {
+        return;
+    }
+    let original = *estimates;
+    let mut assigned = 0;
+    for index in 0..CONVERSATION {
+        estimates[index] = original[index].saturating_mul(total) / special_total;
+        assigned += estimates[index];
+    }
+    let mut remainder = total - assigned;
+    let mut order = (0..CONVERSATION).collect::<Vec<_>>();
+    order.sort_by_key(|index| {
+        std::cmp::Reverse(original[*index].saturating_mul(total) % special_total)
+    });
+    for index in order {
+        if remainder == 0 {
+            break;
+        }
+        estimates[index] += 1;
+        remainder -= 1;
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::model::{CanonicalMessage, Origin, Role};
+
+    #[test]
+    fn breakdown_uses_protocol_categories_and_authoritative_total() {
+        let runtime = CanonicalMessage::text(
+            "runtime",
+            Role::User,
+            Origin::Runtime,
+            "before<rules><user_rule>r</user_rule></rules><agent_skills>s</agent_skills><subagents>a</subagents><mcp_meta_tools>m</mcp_meta_tools>after",
+        );
+        let snapshot = breakdown(
+            1_000,
+            256_000,
+            None,
+            "system",
+            &[],
+            &HashSet::new(),
+            &[runtime],
+        )
+        .unwrap();
+        assert_eq!(
+            snapshot
+                .categories
+                .iter()
+                .map(|category| category.id.as_str())
+                .collect::<Vec<_>>(),
+            CATEGORIES
+                .iter()
+                .map(|category| category.0)
+                .collect::<Vec<_>>()
+        );
+        assert_eq!(
+            snapshot
+                .categories
+                .iter()
+                .map(|category| category.estimated_tokens)
+                .sum::<u32>(),
+            1_000
+        );
+        for id in ["rules", "skills", "mcp", "subagents", "conversation"] {
+            assert!(snapshot
+                .categories
+                .iter()
+                .find(|category| category.id == id)
+                .is_some_and(|category| category.character_count.unwrap_or(0) > 0));
+        }
+        assert_eq!(
+            snapshot.categories[SUMMARY],
+            pb::PromptTokenBreakdownCategory {
+                id: "summarized_conversation".into(),
+                label: "Summarized conversation".into(),
+                ..Default::default()
+            }
+        );
+    }
+
+    #[test]
+    fn conversation_absorbs_the_authoritative_remainder() {
+        let first = breakdown(
+            10_000,
+            256_000,
+            None,
+            "system",
+            &[],
+            &HashSet::new(),
+            &[CanonicalMessage::text(
+                "user",
+                Role::User,
+                Origin::User,
+                "short",
+            )],
+        )
+        .unwrap();
+        let second = breakdown(
+            12_000,
+            256_000,
+            None,
+            "system",
+            &[],
+            &HashSet::new(),
+            &[CanonicalMessage::text(
+                "user",
+                Role::User,
+                Origin::User,
+                "a much longer conversation",
+            )],
+        )
+        .unwrap();
+        assert_eq!(
+            &first.categories[..CONVERSATION],
+            &second.categories[..CONVERSATION]
+        );
+        assert_eq!(
+            second.categories[CONVERSATION].estimated_tokens
+                - first.categories[CONVERSATION].estimated_tokens,
+            2_000
+        );
+    }
+}