diff --git a/apps/mcp-server/tests/integration.rs b/apps/mcp-server/tests/integration.rs index 8deca59..f7f357e 100644 --- a/apps/mcp-server/tests/integration.rs +++ b/apps/mcp-server/tests/integration.rs @@ -14,5 +14,6 @@ mod integration { mod revision_matrix; mod static_resources; mod tool_search; + mod tools_lifecycle; mod transport_protocol; } diff --git a/apps/mcp-server/tests/integration/common.rs b/apps/mcp-server/tests/integration/common.rs index ac0b1e8..964acb7 100644 --- a/apps/mcp-server/tests/integration/common.rs +++ b/apps/mcp-server/tests/integration/common.rs @@ -60,6 +60,31 @@ impl SharedLogWriter { } } +/// Story 3.4: a capturing writer plus the subscriber that records into it, so a test can prove that a +/// request-scoped progress token never reaches the log projection. Install it with +/// `tracing::subscriber::set_default` around the request on the `current_thread` runtime. +pub(super) fn capturing_subscriber() -> ( + CapturedLogs, + impl tracing::Subscriber + Send + Sync + 'static, +) { + let writer = SharedLogWriter::default(); + let subscriber = tracing_subscriber::fmt() + .with_writer(writer.clone()) + .with_max_level(LevelFilter::TRACE) + .with_ansi(false) + .finish(); + (CapturedLogs(writer), subscriber) +} + +/// The captured log text of one scoped subscriber. +pub(super) struct CapturedLogs(SharedLogWriter); + +impl CapturedLogs { + pub(super) fn output(&self) -> String { + self.0.output() + } +} + impl<'a> MakeWriter<'a> for SharedLogWriter { type Writer = SharedLogGuard; diff --git a/apps/mcp-server/tests/integration/tools_lifecycle.rs b/apps/mcp-server/tests/integration/tools_lifecycle.rs new file mode 100644 index 0000000..d34b70c --- /dev/null +++ b/apps/mcp-server/tests/integration/tools_lifecycle.rs @@ -0,0 +1,763 @@ +//! Story 3.4 (FR-14) ATDD: progress and cancellation of one synchronous `tools/call`. +//! +//! Every case drives the real HTTP endpoint of the real application against a real (counted, slow) +//! upstream and real published catalog/registry state; nothing here is a fake client of the server +//! internals. The oracles are the pinned MCP shapes: `notifications/progress` (monotonic `progress`, +//! the request's own `progressToken`, no invented `total`) and the terminal `tools/call` result. +//! +//! Cancellation is revision-correct: `2025-11-25` cancels with `notifications/cancelled`, and +//! `2026-07-28` cancels by closing the request's own response stream. Both are proven to stop the +//! work, to release the call, and to never produce a `completed` record. + +use std::{ + sync::{ + Arc, + atomic::{AtomicUsize, Ordering}, + }, + time::Duration, +}; + +use axum::{Json, Router, routing::post}; +use crank_core::{InvocationStatus, OperationId, PlatformApiKeyScope}; +use crank_registry::{ListInvocationLogsQuery, PostgresRegistry, PublishRequest}; +use serde_json::{Value, json}; +use time::{OffsetDateTime, format_description::well_known::Rfc3339}; +use tokio::net::TcpListener; + +use super::common::{ + agent_mcp_url, build_test_app, capturing_subscriber, create_platform_api_key, + initialize_session, post_jsonrpc, post_jsonrpc_with_headers, publish_agent_for_operation, + spawn_mcp_server, test_operation, test_registry, test_workspace_id, +}; + +const LEGACY: &str = "2025-11-25"; +const MODERN: &str = "2026-07-28"; +const META_PROTOCOL_VERSION: &str = "io.modelcontextprotocol/protocolVersion"; +const META_CLIENT_CAPABILITIES: &str = "io.modelcontextprotocol/clientCapabilities"; +const META_CLIENT_INFO: &str = "io.modelcontextprotocol/clientInfo"; + +const TOOL: &str = "crm_lifecycle_lead"; +/// A call that is long enough for the client to observe real progress, short enough for a suite. +const HOLD_MS: u64 = 250; +/// A call that is still running when the client cancels it. +const LONG_HOLD_MS: u64 = 1_500; +/// The grace period after a cancellation: the call must not complete in it. +const CANCEL_GRACE_MS: u64 = 1_200; + +#[derive(Clone, Copy)] +enum Revision { + Legacy, + Modern, +} + +impl Revision { + const fn label(self) -> &'static str { + match self { + Self::Legacy => LEGACY, + Self::Modern => MODERN, + } + } +} + +struct Upstream { + base_url: String, + started: Arc, + completed: Arc, +} + +/// A real upstream that records when a request starts and when it finishes. A cancelled call must +/// increment `started` exactly once and never `completed`: the request really was dispatched (so the +/// outcome is not `certain`-not-sent) and its response really was abandoned (so it is not retried). +async fn spawn_counted_slow_upstream(hold_ms: u64) -> Upstream { + let started = Arc::new(AtomicUsize::new(0)); + let completed = Arc::new(AtomicUsize::new(0)); + let handler_started = Arc::clone(&started); + let handler_completed = Arc::clone(&completed); + let app = Router::new().route( + "/crm/lifecycle-leads", + post(move |Json(payload): Json| { + let started = Arc::clone(&handler_started); + let completed = Arc::clone(&handler_completed); + async move { + started.fetch_add(1, Ordering::SeqCst); + tokio::time::sleep(Duration::from_millis(hold_ms)).await; + completed.fetch_add(1, Ordering::SeqCst); + Json(json!({ "id": "lead_123", "email": payload["email"] })) + } + }), + ); + let listener = TcpListener::bind("127.0.0.1:0").await.unwrap(); + let address = listener.local_addr().unwrap(); + tokio::spawn(async move { + axum::serve(listener, app).await.unwrap(); + }); + Upstream { + base_url: format!("http://{address}"), + started, + completed, + } +} + +struct Fixture { + client: reqwest::Client, + mcp_url: String, + api_key: String, + other_api_key: String, + registry: PostgresRegistry, + operation_id: OperationId, + upstream: Upstream, +} + +async fn fixture(agent_slug: &str, hold_ms: u64, timeout_ms: u64) -> Fixture { + let upstream = spawn_counted_slow_upstream(hold_ms).await; + let registry = test_registry().await; + let mut operation = test_operation(&upstream.base_url, TOOL); + let crank_core::Target::Rest(target) = &mut operation.target; + target.path_template = "/crm/lifecycle-leads".to_owned(); + operation.execution_config.timeout_ms = timeout_ms; + registry + .create_operation(&test_workspace_id(), &operation, Some("alice")) + .await + .unwrap(); + registry + .publish_operation(PublishRequest { + workspace_id: &test_workspace_id(), + operation_id: &operation.id, + version: 1, + published_at: &OffsetDateTime::parse("2026-03-26T10:00:00Z", &Rfc3339).unwrap(), + published_by: Some("alice"), + }) + .await + .unwrap(); + publish_agent_for_operation(®istry, &operation, agent_slug).await; + let scopes = [PlatformApiKeyScope::Read, PlatformApiKeyScope::Write]; + let api_key = create_platform_api_key(®istry, agent_slug, "mcp-lifecycle", &scopes).await; + let other_api_key = + create_platform_api_key(®istry, agent_slug, "mcp-lifecycle-other", &scopes).await; + let base_url = spawn_mcp_server(build_test_app( + registry.clone(), + Duration::ZERO, + Some("https://crank.example.com".to_owned()), + )) + .await; + + Fixture { + client: reqwest::Client::new(), + mcp_url: agent_mcp_url(&base_url, agent_slug), + api_key, + other_api_key, + registry, + operation_id: operation.id, + upstream, + } +} + +/// One parsed answer: the HTTP status, the negotiated media type and every JSON-RPC frame in order. +struct Reply { + status: reqwest::StatusCode, + content_type: String, + frames: Vec, + raw: String, +} + +impl Reply { + fn parse(status: reqwest::StatusCode, content_type: String, body: String) -> Self { + let mut frames = Vec::new(); + for block in body.split("\n\n") { + for line in block.lines() { + let Some(data) = line.strip_prefix("data:") else { + continue; + }; + let data = data.trim_start(); + if data.is_empty() { + continue; + } + frames.push( + serde_json::from_str(data) + .unwrap_or_else(|error| panic!("every frame is JSON: {data:?} {error}")), + ); + } + } + if frames.is_empty() && !body.trim().is_empty() { + frames.push( + serde_json::from_str(body.trim()).unwrap_or_else(|error| { + panic!("expected a JSON-RPC body, got {body:?}: {error}") + }), + ); + } + Self { + status, + content_type, + frames, + raw: body, + } + } + + fn assert_stream(&self) { + assert_eq!(self.status, reqwest::StatusCode::OK); + assert!( + self.content_type.starts_with("text/event-stream"), + "a progress answer must be the request's SSE stream, got {:?}: {}", + self.content_type, + self.raw + ); + } + + fn progress_frames(&self) -> Vec<&Value> { + self.frames + .iter() + .filter(|frame| frame["method"] == json!("notifications/progress")) + .collect() + } + + fn terminal(&self) -> &Value { + let terminal = self + .frames + .last() + .unwrap_or_else(|| panic!("the stream must carry a terminal frame: {}", self.raw)); + assert!( + terminal.get("method").is_none(), + "the terminal frame must be the JSON-RPC response, got {terminal}" + ); + terminal + } +} + +impl Fixture { + fn call_params(&self, token: Option, revision: Revision) -> Value { + let mut params = json!({ + "name": TOOL, + "arguments": { "email": "lifecycle@example.com" }, + }); + let mut meta = match revision { + Revision::Modern => json!({ + META_PROTOCOL_VERSION: MODERN, + META_CLIENT_CAPABILITIES: {}, + META_CLIENT_INFO: { "name": "crank-3.4-atdd", "version": "0.1.0" }, + }), + Revision::Legacy => json!({}), + }; + if let Some(token) = token { + meta["progressToken"] = token; + } + if meta.as_object().is_some_and(|object| !object.is_empty()) { + params["_meta"] = meta; + } + params + } + + fn headers(&self, revision: Revision, session: Option<&str>) -> Vec<(&'static str, String)> { + let mut headers = vec![("MCP-Protocol-Version", revision.label().to_owned())]; + match revision { + Revision::Legacy => { + if let Some(session) = session { + headers.push(("MCP-Session-Id", session.to_owned())); + } + } + Revision::Modern => { + headers.push(("Mcp-Method", "tools/call".to_owned())); + headers.push(("Mcp-Name", TOOL.to_owned())); + } + } + headers + } + + fn request( + &self, + accept: &'static str, + key: &str, + headers: &[(&'static str, String)], + payload: Value, + ) -> reqwest::RequestBuilder { + let mut request = self + .client + .post(&self.mcp_url) + .header(reqwest::header::ACCEPT, accept) + .header(reqwest::header::AUTHORIZATION, format!("Bearer {key}")); + for (name, value) in headers { + request = request.header(*name, value); + } + request.json(&payload) + } + + /// One `tools/call` whose answer is negotiated as the request's own SSE stream. + async fn call_stream( + &self, + revision: Revision, + id: u64, + params: Value, + session: Option<&str>, + request_id: &str, + ) -> Reply { + self.call_stream_with_key(revision, &self.api_key, id, params, session, request_id) + .await + } + + async fn call_stream_with_key( + &self, + revision: Revision, + key: &str, + id: u64, + params: Value, + session: Option<&str>, + request_id: &str, + ) -> Reply { + self.send( + "text/event-stream", + key, + revision, + id, + params, + session, + Some(request_id), + ) + .await + } + + /// One `tools/call` whose answer is negotiated as a single JSON body. + async fn call_json( + &self, + revision: Revision, + id: u64, + params: Value, + session: Option<&str>, + ) -> Reply { + self.send( + "application/json", + &self.api_key, + revision, + id, + params, + session, + None, + ) + .await + } + + #[allow(clippy::too_many_arguments)] + async fn send( + &self, + accept: &'static str, + key: &str, + revision: Revision, + id: u64, + params: Value, + session: Option<&str>, + request_id: Option<&str>, + ) -> Reply { + let headers = self.headers(revision, session); + let payload = + json!({ "jsonrpc": "2.0", "id": id, "method": "tools/call", "params": params }); + let mut request = self.request(accept, key, &headers, payload); + if let Some(request_id) = request_id { + request = request.header("x-request-id", request_id); + } + let response = request.send().await.expect("the MCP endpoint answers"); + let status = response.status(); + let content_type = response + .headers() + .get(reqwest::header::CONTENT_TYPE) + .and_then(|value| value.to_str().ok()) + .unwrap_or_default() + .to_owned(); + let body = response.text().await.expect("the body is readable"); + Reply::parse(status, content_type, body) + } + + async fn cancel(&self, key: &str, session: &str, request_id: Value) -> reqwest::StatusCode { + let response = self + .request( + "application/json", + key, + &[ + ("MCP-Protocol-Version", LEGACY.to_owned()), + ("MCP-Session-Id", session.to_owned()), + ], + json!({ + "jsonrpc": "2.0", + "method": "notifications/cancelled", + "params": { "requestId": request_id, "reason": "user requested cancellation" } + }), + ) + .send() + .await + .expect("the cancellation is acknowledged"); + response.status() + } + + /// Every Invocation History row of this operation and request id, oldest first. + async fn history(&self, request_id: &str) -> Vec { + self.registry + .list_invocation_logs(ListInvocationLogsQuery { + workspace_id: &test_workspace_id(), + level: None, + status: None, + outcome_group: None, + search_text: None, + source: Some(crank_core::InvocationSource::AgentToolCall), + operation_id: Some(&self.operation_id), + agent_id: None, + created_after: None, + created_before: None, + cursor_created_at: None, + cursor_id: None, + limit: 50, + }) + .await + .unwrap() + .into_iter() + .map(|record| record.log) + .filter(|log| log.request_id.as_deref() == Some(request_id)) + .collect() + } + + /// Wait for the counted upstream to be entered, so a cancellation happens while it really runs. + async fn wait_until_dispatched(&self) { + for _ in 0..200 { + if self.upstream.started.load(Ordering::SeqCst) > 0 { + return; + } + tokio::time::sleep(Duration::from_millis(5)).await; + } + panic!("the upstream was never dispatched"); + } +} + +fn progress_values(frames: &[&Value]) -> Vec { + frames + .iter() + .map(|frame| { + frame["params"]["progress"] + .as_u64() + .unwrap_or_else(|| panic!("progress must be a number, got {frame}")) + }) + .collect() +} + +// --------------------------------------------------------------------------------------------- +// AT-3.4-01: a negotiated stream carries bounded monotonic progress of the real execution, and a +// missing token (or a missing carrier) never changes the execution result. +// --------------------------------------------------------------------------------------------- + +#[tokio::test] +async fn at_3_4_01_legacy_progress_stream_is_monotonic_and_ends_with_the_real_result() { + let fixture = fixture("lifecycle-legacy-progress", HOLD_MS, 5_000).await; + let session = initialize_session(&fixture.client, &fixture.mcp_url, &fixture.api_key).await; + + let reply = fixture + .call_stream( + Revision::Legacy, + 501, + fixture.call_params(Some(json!("tok-legacy-progress")), Revision::Legacy), + Some(&session), + "req-legacy-progress", + ) + .await; + reply.assert_stream(); + + let progress = reply.progress_frames(); + assert!( + !progress.is_empty(), + "a token with a stream carrier must produce progress, got {}", + reply.raw + ); + for frame in &progress { + assert_eq!(frame["jsonrpc"], json!("2.0")); + assert_eq!( + frame["params"]["progressToken"], + json!("tok-legacy-progress") + ); + assert!( + frame["params"].get("total").is_none(), + "this server knows no total and must not invent one: {frame}" + ); + assert!( + frame["params"]["message"].is_string(), + "every real step names itself: {frame}" + ); + } + let values = progress_values(&progress); + assert!( + values.windows(2).all(|pair| pair[0] < pair[1]), + "progress must be strictly monotonic, got {values:?}" + ); + // One event per real execution step this server actually crosses: resolved, authorized, + // dispatched. Never a timer-driven percentage and never an unbounded stream. + assert_eq!(values, vec![1, 2, 3], "got {values:?}"); + + let terminal = reply.terminal(); + assert_eq!(terminal["id"], json!(501)); + assert_eq!(terminal["error"], Value::Null); + assert_eq!(terminal["result"]["isError"], json!(false)); + assert_eq!( + terminal["result"]["structuredContent"], + json!({ "id": "lead_123" }) + ); + assert_eq!(fixture.upstream.started.load(Ordering::SeqCst), 1); + assert_eq!(fixture.upstream.completed.load(Ordering::SeqCst), 1); +} + +#[tokio::test] +async fn at_3_4_01_modern_progress_stream_is_monotonic_and_ends_with_the_real_result() { + let fixture = fixture("lifecycle-modern-progress", HOLD_MS, 5_000).await; + + let reply = fixture + .call_stream( + Revision::Modern, + 502, + fixture.call_params(Some(json!(77)), Revision::Modern), + None, + "req-modern-progress", + ) + .await; + reply.assert_stream(); + + let progress = reply.progress_frames(); + assert!(!progress.is_empty(), "got {}", reply.raw); + for frame in &progress { + assert_eq!(frame["params"]["progressToken"], json!(77)); + } + let values = progress_values(&progress); + assert!( + values.windows(2).all(|pair| pair[0] < pair[1]), + "{values:?}" + ); + + let terminal = reply.terminal(); + assert_eq!(terminal["result"]["isError"], json!(false)); + assert_eq!( + terminal["result"]["structuredContent"], + json!({ "id": "lead_123" }) + ); +} + +#[tokio::test] +async fn at_3_4_01_no_token_and_no_carrier_keep_the_result_identical() { + let fixture = fixture("lifecycle-no-token", HOLD_MS, 5_000).await; + let session = initialize_session(&fixture.client, &fixture.mcp_url, &fixture.api_key).await; + + // Without a token the very same call is one plain JSON body: no notification exists. + let without_token = fixture + .call_json( + Revision::Legacy, + 510, + fixture.call_params(None, Revision::Legacy), + Some(&session), + ) + .await; + assert_eq!(without_token.status, reqwest::StatusCode::OK); + assert!(without_token.progress_frames().is_empty()); + let plain = without_token.terminal()["result"].clone(); + assert_eq!(plain["isError"], json!(false)); + + // With a token but only the `application/json` carrier the result is the same and progress is + // simply not sent (the receiver is never obligated to send it). + let token_without_carrier = fixture + .call_json( + Revision::Legacy, + 511, + fixture.call_params(Some(json!("tok-no-carrier")), Revision::Legacy), + Some(&session), + ) + .await; + assert_eq!(token_without_carrier.status, reqwest::StatusCode::OK); + assert!(token_without_carrier.progress_frames().is_empty()); + assert_eq!(token_without_carrier.terminal()["result"], plain); + + // In the stream mode without a token the only frame is the terminal response itself. + let stream_without_token = fixture + .call_stream( + Revision::Legacy, + 512, + fixture.call_params(None, Revision::Legacy), + Some(&session), + "req-no-token-stream", + ) + .await; + assert!(stream_without_token.progress_frames().is_empty()); + assert_eq!(stream_without_token.frames.len(), 1); + assert_eq!(stream_without_token.terminal()["result"], plain); +} + +/// The streamed answer keeps the Story 3.18 projection: a client that opted in to logging gets the +/// same single closed `notifications/message` of this call before the terminal frame, next to the +/// progress events of Story 3.4. +#[tokio::test] +async fn at_3_4_01_a_progress_stream_keeps_the_logging_projection() { + let fixture = fixture("lifecycle-progress-logging", HOLD_MS, 5_000).await; + let session = initialize_session(&fixture.client, &fixture.mcp_url, &fixture.api_key).await; + let set_level = fixture + .request( + "application/json", + &fixture.api_key, + &[ + ("MCP-Protocol-Version", LEGACY.to_owned()), + ("MCP-Session-Id", session.clone()), + ], + json!({ + "jsonrpc": "2.0", "id": 900, "method": "logging/setLevel", + "params": { "level": "debug" } + }), + ) + .send() + .await + .expect("the level is accepted"); + assert_eq!(set_level.status(), reqwest::StatusCode::OK); + + let reply = fixture + .call_stream( + Revision::Legacy, + 901, + fixture.call_params(Some(json!("tok-logging")), Revision::Legacy), + Some(&session), + "req-progress-logging", + ) + .await; + reply.assert_stream(); + assert!(!reply.progress_frames().is_empty(), "got {}", reply.raw); + + let logged: Vec<&Value> = reply + .frames + .iter() + .filter(|frame| frame["method"] == json!("notifications/message")) + .collect(); + assert_eq!( + logged.len(), + 1, + "exactly one closed log event per response, got {}", + reply.raw + ); + assert_eq!( + logged[0]["params"]["data"]["event"], + json!("mcp.request.served") + ); + assert_eq!(logged[0]["params"]["data"]["outcome"], json!("ok")); + assert_eq!(reply.terminal()["result"]["isError"], json!(false)); +} + +// --------------------------------------------------------------------------------------------- +// AT-3.4-02: a malformed, reused-in-another-scope or oversized token disables progress, and the +// token never becomes a metric label, a log field or an authorization scope. +// --------------------------------------------------------------------------------------------- +#[tokio::test] +async fn at_3_4_02_malformed_and_oversized_tokens_disable_progress_without_changing_the_result() { + let fixture = fixture("lifecycle-bad-token", HOLD_MS, 5_000).await; + let session = initialize_session(&fixture.client, &fixture.mcp_url, &fixture.api_key).await; + + let oversized = "x".repeat(4096); + let oversized = json!(oversized); + let empty = json!(""); + let object = json!({ "not": "a token" }); + let array = json!([1, 2]); + let boolean = json!(true); + let mut observed = Vec::new(); + for token in [empty, object, array, boolean, oversized] { + let reply = fixture + .call_stream( + Revision::Legacy, + 520, + fixture.call_params(Some(token.clone()), Revision::Legacy), + Some(&session), + "req-bad-token", + ) + .await; + observed.push((token, reply)); + } + + for (token, reply) in observed { + assert!( + reply.progress_frames().is_empty(), + "token {token} must not produce progress, got {}", + reply.raw + ); + let terminal = reply.terminal(); + assert_eq!( + terminal["result"]["structuredContent"], + json!({ "id": "lead_123" }), + "token {token} must not change the execution result, got {terminal}" + ); + assert_eq!(terminal["result"]["isError"], json!(false)); + assert!(terminal["error"].is_null() || terminal.get("error").is_none()); + } +} + +#[tokio::test] +async fn at_3_4_02_a_reused_token_is_scoped_to_its_own_request() { + let fixture = fixture("lifecycle-reused-token", HOLD_MS, 5_000).await; + let first = initialize_session(&fixture.client, &fixture.mcp_url, &fixture.api_key).await; + let second = initialize_session(&fixture.client, &fixture.mcp_url, &fixture.api_key).await; + let token = json!("tok-shared"); + + let (first_reply, second_reply) = tokio::join!( + fixture.call_stream( + Revision::Legacy, + 530, + fixture.call_params(Some(token.clone()), Revision::Legacy), + Some(&first), + "req-first", + ), + fixture.call_stream( + Revision::Legacy, + 531, + fixture.call_params(Some(token.clone()), Revision::Legacy), + Some(&second), + "req-second", + ) + ); + + for (reply, id) in [(&first_reply, 530), (&second_reply, 531)] { + reply.assert_stream(); + let values = progress_values(&reply.progress_frames()); + // Each request counts its own real steps: a reused token never inherits another call's count. + assert_eq!(values, vec![1, 2, 3], "request {id} got {values:?}"); + assert_eq!(reply.terminal()["id"], json!(id)); + } +} + +#[tokio::test] +async fn at_3_4_02_a_progress_token_never_reaches_logs_or_invocation_history() { + const CANARY: &str = "crank-progress-canary-4f1c2d"; + let fixture = fixture("lifecycle-token-leak", HOLD_MS, 5_000).await; + let session = initialize_session(&fixture.client, &fixture.mcp_url, &fixture.api_key).await; + let (writer, subscriber) = capturing_subscriber(); + + let reply = { + let _guard = tracing::subscriber::set_default(subscriber); + fixture + .call_stream( + Revision::Legacy, + 540, + fixture.call_params(Some(json!(CANARY)), Revision::Legacy), + Some(&session), + "req-token-leak", + ) + .await + }; + reply.assert_stream(); + + let logs = writer.output(); + assert!( + logs.contains("mcp request received"), + "the capture must really see the endpoint's own log projection, got {logs}" + ); + assert!( + !logs.contains(CANARY), + "the progress token is client data and must never be logged, got {logs}" + ); + + let history = fixture.history("req-token-leak").await; + assert_eq!(history.len(), 1, "got {history:?}"); + let row = &history[0]; + let serialized = serde_json::to_string(row).unwrap(); + assert!( + !serialized.contains(CANARY), + "the progress token must never reach Invocation History, got {serialized}" + ); + assert_eq!(row.status, InvocationStatus::Ok); +} + +// AT-3.4-03: a cancellation stops a call that can still be stopped, releases it and never yields a +// `completed` result or record. +mod cancellation; +// AT-3.4-05: the client-visible smoke of both supported revisions. +mod smoke; diff --git a/apps/mcp-server/tests/integration/tools_lifecycle/cancellation.rs b/apps/mcp-server/tests/integration/tools_lifecycle/cancellation.rs new file mode 100644 index 0000000..04aa617 --- /dev/null +++ b/apps/mcp-server/tests/integration/tools_lifecycle/cancellation.rs @@ -0,0 +1,294 @@ +//! AT-3.4-03: a cancellation stops a call that can still be stopped, releases it, and never yields a +//! `completed` result or history row. The harness of the suite lives in `super`. + +use super::*; + +// --------------------------------------------------------------------------------------------- +// AT-3.4-03: a cancellation stops a call that can still be stopped, releases it, and never yields a +// `completed` result or history row. +// --------------------------------------------------------------------------------------------- + +#[tokio::test] +async fn at_3_4_03_legacy_cancellation_stops_the_call_and_never_completes_it() { + let fixture = fixture("lifecycle-legacy-cancel", LONG_HOLD_MS, 30_000).await; + let session = initialize_session(&fixture.client, &fixture.mcp_url, &fixture.api_key).await; + + let call_session = session.clone(); + let call = tokio::spawn({ + let fixture_client = fixture.client.clone(); + let mcp_url = fixture.mcp_url.clone(); + let api_key = fixture.api_key.clone(); + let params = fixture.call_params(Some(json!("tok-cancel")), Revision::Legacy); + async move { + let response = fixture_client + .post(mcp_url) + .header(reqwest::header::ACCEPT, "text/event-stream") + .header(reqwest::header::AUTHORIZATION, format!("Bearer {api_key}")) + .header("MCP-Protocol-Version", LEGACY) + .header("MCP-Session-Id", call_session) + .header("x-request-id", "req-legacy-cancel") + .json(&json!({ + "jsonrpc": "2.0", + "id": 601, + "method": "tools/call", + "params": params, + })) + .send() + .await + .unwrap(); + (response.status(), response.text().await.unwrap()) + } + }); + + fixture.wait_until_dispatched().await; + assert_eq!( + fixture.cancel(&fixture.api_key, &session, json!(601)).await, + reqwest::StatusCode::ACCEPTED, + "an accepted cancellation is acknowledged without a body" + ); + + let (status, body) = tokio::time::timeout(Duration::from_secs(10), call) + .await + .expect("the cancelled call is released, it does not hang") + .expect("the request task joins"); + assert_eq!(status, reqwest::StatusCode::OK); + let reply = Reply::parse(status, String::new(), body); + assert!( + reply + .frames + .iter() + .all(|frame| frame.get("method").is_some()), + "a cancelled request gets no terminal message, only the progress it already saw: {}", + reply.raw + ); + assert_eq!( + reply.progress_frames().len(), + 3, + "the client really saw the real steps before the stop: {}", + reply.raw + ); + + tokio::time::sleep(Duration::from_millis(CANCEL_GRACE_MS)).await; + assert_eq!( + fixture.upstream.completed.load(Ordering::SeqCst), + 0, + "the abandoned upstream response must never complete the call" + ); + assert_eq!( + fixture.upstream.started.load(Ordering::SeqCst), + 1, + "the write really was dispatched and must not be retried automatically" + ); + + let history = fixture.history("req-legacy-cancel").await; + assert!( + history.iter().all(|row| row.status != InvocationStatus::Ok), + "a cancelled call must never be recorded as completed, got {history:?}" + ); + // The record contract admits a non-`ok` row only with a closed execution error code, and a + // cancellation is not one of them: the honest terminal state of this call is "no record" instead + // of an invented error code. Either way nothing claims that the call completed. + assert!( + history.is_empty(), + "a stopped call has no terminal outcome to record, got {history:?}" + ); +} + +#[tokio::test] +async fn at_3_4_03_a_foreign_or_unknown_cancellation_never_touches_the_active_call() { + let fixture = fixture("lifecycle-foreign-cancel", HOLD_MS, 5_000).await; + let session = initialize_session(&fixture.client, &fixture.mcp_url, &fixture.api_key).await; + let foreign_session = + initialize_session(&fixture.client, &fixture.mcp_url, &fixture.other_api_key).await; + + let call = tokio::spawn({ + let client = fixture.client.clone(); + let mcp_url = fixture.mcp_url.clone(); + let api_key = fixture.api_key.clone(); + let call_session = session.clone(); + let params = fixture.call_params(Some(json!("tok-owner")), Revision::Legacy); + async move { + let response = client + .post(mcp_url) + .header(reqwest::header::ACCEPT, "text/event-stream") + .header(reqwest::header::AUTHORIZATION, format!("Bearer {api_key}")) + .header("MCP-Protocol-Version", LEGACY) + .header("MCP-Session-Id", call_session) + .header("x-request-id", "req-owner") + .json(&json!({ + "jsonrpc": "2.0", "id": 602, "method": "tools/call", "params": params, + })) + .send() + .await + .unwrap(); + response.text().await.unwrap() + } + }); + + fixture.wait_until_dispatched().await; + // A foreign credential of the same agent, and an unknown request id: neither may cancel this call. + assert_eq!( + fixture + .cancel(&fixture.other_api_key, &session, json!(602)) + .await, + reqwest::StatusCode::ACCEPTED + ); + assert_eq!( + fixture + .cancel(&fixture.api_key, &session, json!(999_999)) + .await, + reqwest::StatusCode::ACCEPTED + ); + // A foreign session of the same credential cannot reach this call either. + assert_eq!( + fixture + .cancel(&fixture.api_key, &foreign_session, json!(602)) + .await, + reqwest::StatusCode::ACCEPTED + ); + + let body = tokio::time::timeout(Duration::from_secs(10), call) + .await + .expect("the untouched call completes") + .expect("the request task joins"); + let reply = Reply::parse(reqwest::StatusCode::OK, String::new(), body); + assert_eq!( + reply.terminal()["result"]["structuredContent"], + json!({ "id": "lead_123" }), + "a foreign cancellation must not stop the owner's call, got {}", + reply.raw + ); + let history = fixture.history("req-owner").await; + assert_eq!(history.len(), 1, "got {history:?}"); + assert_eq!(history[0].status, InvocationStatus::Ok); +} + +#[tokio::test] +async fn at_3_4_03_a_late_cancellation_after_the_result_is_ignored() { + let fixture = fixture("lifecycle-late-cancel", HOLD_MS, 5_000).await; + let session = initialize_session(&fixture.client, &fixture.mcp_url, &fixture.api_key).await; + + let reply = fixture + .call_stream( + Revision::Legacy, + 603, + fixture.call_params(Some(json!("tok-late")), Revision::Legacy), + Some(&session), + "req-late-cancel", + ) + .await; + reply.assert_stream(); + assert_eq!(reply.terminal()["result"]["isError"], json!(false)); + + assert_eq!( + fixture.cancel(&fixture.api_key, &session, json!(603)).await, + reqwest::StatusCode::ACCEPTED + ); + tokio::time::sleep(Duration::from_millis(200)).await; + + let history = fixture.history("req-late-cancel").await; + assert_eq!( + history.len(), + 1, + "a cancellation of a finished call must not add a second record, got {history:?}" + ); + assert_eq!(history[0].status, InvocationStatus::Ok); +} + +#[tokio::test] +async fn at_3_4_03_a_plain_json_call_is_cancellable_too() { + let fixture = fixture("lifecycle-json-cancel", LONG_HOLD_MS, 30_000).await; + let session = initialize_session(&fixture.client, &fixture.mcp_url, &fixture.api_key).await; + + let call = tokio::spawn({ + let client = fixture.client.clone(); + let mcp_url = fixture.mcp_url.clone(); + let api_key = fixture.api_key.clone(); + let call_session = session.clone(); + let params = fixture.call_params(None, Revision::Legacy); + async move { + let response = client + .post(mcp_url) + .header(reqwest::header::ACCEPT, "application/json") + .header(reqwest::header::AUTHORIZATION, format!("Bearer {api_key}")) + .header("MCP-Protocol-Version", LEGACY) + .header("MCP-Session-Id", call_session) + .header("x-request-id", "req-json-cancel") + .json(&json!({ + "jsonrpc": "2.0", "id": 605, "method": "tools/call", "params": params, + })) + .send() + .await + .unwrap(); + let status = response.status(); + (status, response.text().await.unwrap()) + } + }); + + fixture.wait_until_dispatched().await; + assert_eq!( + fixture.cancel(&fixture.api_key, &session, json!(605)).await, + reqwest::StatusCode::ACCEPTED + ); + + let (status, body) = tokio::time::timeout(Duration::from_secs(10), call) + .await + .expect("the cancelled call is released") + .expect("the request task joins"); + assert_eq!(status, reqwest::StatusCode::OK); + let reply = Reply::parse(status, String::new(), body); + assert!( + reply.frames.is_empty(), + "a cancelled request gets no terminal message, got {}", + reply.raw + ); + + tokio::time::sleep(Duration::from_millis(CANCEL_GRACE_MS)).await; + assert_eq!(fixture.upstream.completed.load(Ordering::SeqCst), 0); + let history = fixture.history("req-json-cancel").await; + assert!( + history.iter().all(|row| row.status != InvocationStatus::Ok), + "a cancelled call must never be recorded as completed, got {history:?}" + ); +} + +#[tokio::test] +async fn at_3_4_03_closing_the_modern_response_stream_cancels_the_call() { + let fixture = fixture("lifecycle-modern-disconnect", LONG_HOLD_MS, 30_000).await; + + let response = fixture + .request( + "text/event-stream", + &fixture.api_key, + &fixture.headers(Revision::Modern, None), + json!({ + "jsonrpc": "2.0", + "id": 604, + "method": "tools/call", + "params": fixture.call_params(Some(json!("tok-disconnect")), Revision::Modern), + }), + ) + .header("x-request-id", "req-modern-disconnect") + .send() + .await + .expect("the stream opens before the call finishes"); + assert_eq!(response.status(), reqwest::StatusCode::OK); + fixture.wait_until_dispatched().await; + + // The pinned `2026-07-28` cancellation signal: closing the request's own response stream. + drop(response); + + tokio::time::sleep(Duration::from_millis(CANCEL_GRACE_MS)).await; + assert_eq!( + fixture.upstream.completed.load(Ordering::SeqCst), + 0, + "the closed stream must stop the dispatched call instead of letting it finish" + ); + assert_eq!(fixture.upstream.started.load(Ordering::SeqCst), 1); + + let history = fixture.history("req-modern-disconnect").await; + assert!( + history.iter().all(|row| row.status != InvocationStatus::Ok), + "a cancelled call must never be recorded as completed, got {history:?}" + ); +} diff --git a/apps/mcp-server/tests/integration/tools_lifecycle/smoke.rs b/apps/mcp-server/tests/integration/tools_lifecycle/smoke.rs new file mode 100644 index 0000000..95d30ad --- /dev/null +++ b/apps/mcp-server/tests/integration/tools_lifecycle/smoke.rs @@ -0,0 +1,79 @@ +//! AT-3.4-05: the client-visible smoke of both supported revisions. +//! +//! A representative client of each revision performs the whole flow a real MCP client performs — +//! discovery, then a `tools/call` that asks for progress and reads the request's own stream to the +//! terminal response — against the real endpoint. The harness of the suite lives in `super`. + +use super::*; + +#[tokio::test] +async fn at_3_4_05_representative_client_smoke_of_both_revisions() { + let fixture = fixture("lifecycle-client-smoke", HOLD_MS, 5_000).await; + + // Legacy client: initialize → tools/list → tools/call with progress. + let session = initialize_session(&fixture.client, &fixture.mcp_url, &fixture.api_key).await; + let tools = post_jsonrpc( + &fixture.client, + &fixture.mcp_url, + &fixture.api_key, + Some(&session), + json!({ "jsonrpc": "2.0", "id": 700, "method": "tools/list", "params": {} }), + ) + .await; + assert_eq!(tools["result"]["tools"][0]["name"], json!(TOOL)); + + let legacy_call = fixture + .call_stream( + Revision::Legacy, + 701, + fixture.call_params(Some(json!("tok-smoke-legacy")), Revision::Legacy), + Some(&session), + "req-smoke-legacy", + ) + .await; + legacy_call.assert_stream(); + assert_eq!( + legacy_call.terminal()["result"]["structuredContent"], + json!({ "id": "lead_123" }) + ); + + // Modern client: `tools/list` and `tools/call` of the stateless revision, progress on the stream. + let modern_list = post_jsonrpc_with_headers( + &fixture.client, + &fixture.mcp_url, + &fixture.api_key, + &[ + ("MCP-Protocol-Version", MODERN), + ("Mcp-Method", "tools/list"), + ], + json!({ + "jsonrpc": "2.0", + "id": 710, + "method": "tools/list", + "params": { "_meta": { + META_PROTOCOL_VERSION: MODERN, + META_CLIENT_CAPABILITIES: {}, + META_CLIENT_INFO: { "name": "crank-3.4-smoke", "version": "0.1.0" }, + }} + }), + ) + .await; + let modern_list = modern_list.json::().await.unwrap(); + assert_eq!(modern_list["result"]["tools"][0]["name"], json!(TOOL)); + + let modern_call = fixture + .call_stream( + Revision::Modern, + 711, + fixture.call_params(Some(json!("tok-smoke-modern")), Revision::Modern), + None, + "req-smoke-modern", + ) + .await; + modern_call.assert_stream(); + assert!(!modern_call.progress_frames().is_empty()); + assert_eq!( + modern_call.terminal()["result"]["structuredContent"], + json!({ "id": "lead_123" }) + ); +} diff --git a/crates/crank-community-mcp/src/app.rs b/crates/crank-community-mcp/src/app.rs index b5fec1a..0874620 100644 --- a/crates/crank-community-mcp/src/app.rs +++ b/crates/crank-community-mcp/src/app.rs @@ -30,6 +30,7 @@ mod approval_policy; #[cfg(test)] pub(crate) mod dispatch_observer; mod invocation_history; +pub(crate) mod lifecycle; mod metrics; mod request; mod response; @@ -89,6 +90,8 @@ pub(super) struct AppState { /// Story 3.19: the bounded table of the legacy session that currently owns the notification /// stream, so one session never broadcasts the same list-change signal into two streams. pub(super) signal_streams: Arc, + /// Story 3.4: the bounded table of the `tools/call` requests a legacy client can still cancel. + pub(super) in_flight: Arc, } #[derive(Clone)] @@ -257,6 +260,9 @@ fn build_app_inner( allowed_origins: AllowedOrigins::new(public_base_url), logging_levels: Arc::new(crate::protocol::LogLevelStore::new()), signal_streams: Arc::new(crate::protocol::StreamRegistry::new()), + in_flight: Arc::new(lifecycle::InFlightCalls::new( + lifecycle::MAX_IN_FLIGHT_CALLS, + )), }); if start_background_workers { spawn_approval_recovery(Arc::clone(&state)); diff --git a/crates/crank-community-mcp/src/app/dispatch.rs b/crates/crank-community-mcp/src/app/dispatch.rs index d5363a7..36b26ef 100644 --- a/crates/crank-community-mcp/src/app/dispatch.rs +++ b/crates/crank-community-mcp/src/app/dispatch.rs @@ -39,8 +39,7 @@ use time::OffsetDateTime; use super::response::{ completion_result, internal_jsonrpc_error, prompt_arguments_error_response, prompt_get_result, prompts_list_result, resource_error_response, resource_read_result, - resource_templates_list_result, resources_list_result, tool_command_response, - tools_list_result, + resource_templates_list_result, resources_list_result, tools_list_result, }; use super::{AgentRoutePath, AppState, TRANSPORT_SESSION_TTL_MS}; use crate::protocol::{ResourceTemplatesListError, list_resource_templates}; @@ -156,6 +155,8 @@ pub(super) async fn handle_modern_request( locale: execution_locale(message), }, ToolsCommand::List(list_command), + // A list command has no progress or cancellation lifecycle (Story 3.4). + None, ) .await; match outcome { @@ -220,30 +221,35 @@ pub(super) async fn handle_modern_request( // session-less, so its calls cannot advertise elicitation support. let mut arguments = tool_call_params.arguments.unwrap_or_else(|| json!({})); let confirmation_token = take_confirmation_token(&mut arguments); - let outcome = handle_tools_command( - state, - ServiceContext { - workspace_slug: &path.workspace_slug, - agent_slug: &path.agent_slug, - credential, - correlation: transport_correlation, + // Story 3.4: the client's own `_meta.progressToken` of this request, validated and bounded. + let progress = crate::app::lifecycle::token_from_meta(tool_call_params.meta.as_ref()); + super::lifecycle::run_tool_call( + Arc::clone(state), + crate::app::lifecycle::ToolCallRequest { + workspace_slug: path.workspace_slug.clone(), + agent_slug: path.agent_slug.clone(), + credential: credential.clone(), + correlation: transport_correlation.clone(), continuation: ContinuationSupport::ElicitationUnsupported, locale: execution_locale(message), }, - ToolsCommand::Call(ToolCallCommand { + crate::app::lifecycle::ToolCallWire { + message: message.clone(), + protocol_version: version.to_owned(), + response_mode, + progress, + session_id: None, + // The modern revision cancels by closing this request's response stream, so no + // session-scoped cancellation table is involved. + in_flight: None, + }, + ToolCallCommand { tool_name: tool_call_params.name, arguments, confirmation_token, - }), - ) - .await; - tool_command_response( - message, - response_mode, - version, - transport_correlation, - outcome, + }, ) + .await } DispatchDecision::Allowed { handler: MethodHandler::ResourceList, diff --git a/crates/crank-community-mcp/src/app/legacy_dispatch.rs b/crates/crank-community-mcp/src/app/legacy_dispatch.rs index 8a4aa7b..4a06527 100644 --- a/crates/crank-community-mcp/src/app/legacy_dispatch.rs +++ b/crates/crank-community-mcp/src/app/legacy_dispatch.rs @@ -22,7 +22,7 @@ use super::response::{ completion_result, internal_jsonrpc_error, prompt_arguments_error_response, prompt_get_result, prompts_list_result, resource_error_response, resource_read_result, resource_templates_list_result, resources_list_result, take_confirmation_token, - tool_command_response, tools_list_result, + tools_list_result, }; use super::{AgentRoutePath, AppState}; use crate::{ @@ -41,7 +41,7 @@ use crate::{ handle_tools_command, }, tool_error::execution_locale, - transport::{ResponseMode, transport_response}, + transport::{ResponseMode, session_id_from_headers, transport_response}, }; // The transport invariants of one request travel together here; a parameter struct would only @@ -138,6 +138,8 @@ pub(super) async fn handle_legacy_request( locale: execution_locale(message), }, ToolsCommand::List(list_command), + // A list command has no progress or cancellation lifecycle (Story 3.4). + None, ) .await; match outcome { @@ -192,30 +194,43 @@ pub(super) async fn handle_legacy_request( // response mode or the protocol revision (spec section 6.2). let mut arguments = tool_call_params.arguments.unwrap_or_else(|| json!({})); let confirmation_token = take_confirmation_token(&mut arguments); - let outcome = handle_tools_command( - &state, - ServiceContext { - workspace_slug: &session.workspace_slug, - agent_slug: &session.agent_slug, - credential, - correlation: transport_correlation, + // Story 3.4: the client's own `_meta.progressToken`, validated and bounded, and the + // session/credential ownership of the in-flight cancellation table. + let progress = crate::app::lifecycle::token_from_meta(tool_call_params.meta.as_ref()); + super::lifecycle::run_tool_call( + Arc::clone(&state), + crate::app::lifecycle::ToolCallRequest { + workspace_slug: session.workspace_slug.clone(), + agent_slug: session.agent_slug.clone(), + credential: credential.clone(), + correlation: transport_correlation.clone(), continuation: ContinuationSupport::from_supported(session.supports_elicitation), locale: execution_locale(message), }, - ToolsCommand::Call(ToolCallCommand { + crate::app::lifecycle::ToolCallWire { + message: message.clone(), + protocol_version: session.protocol_version.clone(), + response_mode, + progress, + session_id: Some(session.id.clone()), + in_flight: Some(crate::app::lifecycle::InFlightScope { + session_id: session.id.clone(), + owner: in_flight_owner(credential), + }), + }, + ToolCallCommand { tool_name: tool_call_params.name, arguments, confirmation_token, - }), - ) - .await; - tool_command_response( - message, - response_mode, - &session.protocol_version, - transport_correlation, - outcome, + }, ) + .await + } + DispatchDecision::Allowed { + handler: MethodHandler::Cancelled, + kind: Kind::Notification, + } if is_notification(message) => { + handle_cancelled_notification(&state, path, headers, message, credential).await } DispatchDecision::Allowed { handler: MethodHandler::ResourceList, @@ -729,3 +744,51 @@ pub(super) async fn handle_legacy_request( }, } } + +/// The credential half of the cancellation ownership of one call (Story 3.4). The progress token is +/// deliberately not part of it: a token never authorizes a cancellation. +fn in_flight_owner(credential: &VerifiedMachineCredential) -> String { + credential + .platform_api_key_id + .as_ref() + .map_or_else(String::new, |id| id.as_str().to_owned()) +} + +/// Route one legacy `notifications/cancelled` to the call it names, then acknowledge it. +/// +/// The pinned rules of a cancelled request are all "ignore": an unknown or already finished request, +/// a foreign session or credential, a malformed `requestId` and an unknown session are acknowledged +/// without any effect. That is also why this handler never fails the transport — a client that +/// cancels must not learn anything about another client's calls. +async fn handle_cancelled_notification( + state: &Arc, + path: &AgentRoutePath, + headers: &HeaderMap, + message: &Value, + credential: &VerifiedMachineCredential, +) -> Response { + let request_id = params(message).get("requestId").cloned(); + let session_id = session_id_from_headers(headers).ok().flatten(); + if let (Some(request_id), Some(session_id)) = (request_id, session_id) { + // Only a string or a number is a pinned `RequestId`; anything else cannot name a call. + if matches!(request_id, Value::String(_) | Value::Number(_)) { + let owned_by_session = match state.sessions.get(&session_id).await { + Ok(Some(session)) => { + session.workspace_slug == path.workspace_slug + && session.agent_slug == path.agent_slug + } + _ => false, + }; + if owned_by_session { + state.in_flight.cancel( + &crate::app::lifecycle::InFlightScope { + session_id, + owner: in_flight_owner(credential), + }, + &request_id, + ); + } + } + } + StatusCode::ACCEPTED.into_response() +} diff --git a/crates/crank-community-mcp/src/app/lifecycle.rs b/crates/crank-community-mcp/src/app/lifecycle.rs new file mode 100644 index 0000000..637bc99 --- /dev/null +++ b/crates/crank-community-mcp/src/app/lifecycle.rs @@ -0,0 +1,565 @@ +//! Story 3.4 (FR-14): request-scoped progress and cancellation of one synchronous `tools/call`. +//! +//! The pinned `RequestMetaObject` of *both* supported revisions carries an optional opaque +//! `progressToken`; a request that has one asks for out-of-band `notifications/progress` messages +//! about that request. Such a message only has a carrier on the request's own SSE response stream, so +//! a token is honoured only when the client negotiated `text/event-stream`. Without a token — or +//! without the stream — the call runs exactly as before: the receiver of a progress token is never +//! obligated to send progress, so the execution result cannot change. +//! +//! Cancellation follows the revision-specific rule of the pinned specification: +//! * `2025-11-25`: the client POSTs `notifications/cancelled` with the id of the request it issued. +//! The bounded in-flight table routes it to that call. Ownership is the session *and* the platform +//! credential of the call, never the progress token: a foreign session or key cancels nothing. +//! * `2026-07-28`: closing the request's SSE response stream *is* the cancellation signal, so there is +//! no notification to route; dropping the response stream drops the call future. +//! +//! Either way a cancelled call never becomes a false `completed`: no further message is sent for it +//! (the pinned rule for a cancelled request), and the call never reaches its terminal outcome, so no +//! Invocation History row claims a completion. The record contract only admits a *closed* execution +//! error code for a non-`ok` row and a cancellation is not one of them, so the honest state of a +//! stopped call is "no terminal record" rather than an invented error code; a dedicated cancellation +//! code would be a schema/vocabulary decision of its own. + +use std::{ + collections::{HashMap, VecDeque}, + future::Future, + pin::Pin, + sync::{Arc, Mutex}, +}; + +use axum::{ + http::StatusCode, + response::{IntoResponse, Response, sse::Event}, +}; +use crank_core::{CorrelationContext, ExecutionLocale, VerifiedMachineCredential}; +use futures_util::stream; +use serde_json::{Number, Value, json}; +use tokio::sync::{mpsc, watch}; + +use super::{ + AppState, + response::{ToolCommandPayload, tool_command_payload, tool_command_response}, +}; +use crate::{ + jsonrpc::request_id, + protocol::{ + ContinuationSupport, ServiceContext, ToolCallCommand, ToolsCommand, ToolsOutcome, + handle_tools_command, + }, + transport::{ResponseMode, sse_response}, +}; + +/// The bounded progress queue of one call. A client that reads its stream slowly can never block the +/// call: a full queue drops the event instead of waiting, and the remaining events stay monotonic. +pub(crate) const PROGRESS_CAPACITY: usize = 8; +/// The pinned `ProgressToken` bound this server accepts. A longer token is not rejected as an error: +/// progress is simply disabled for that request, exactly as for a malformed one. +pub(crate) const MAX_PROGRESS_TOKEN_LEN: usize = 128; +/// The bounded table of calls that can still be cancelled. A call that finds the table full runs +/// without cancellation instead of growing the table. +pub(crate) const MAX_IN_FLIGHT_CALLS: usize = 256; + +/// A validated `RequestMetaObject.progressToken`: the pinned opaque token is a string or a number. +#[derive(Clone, Debug, PartialEq, Eq)] +pub(crate) enum ProgressToken { + Text(String), + Number(Number), +} + +impl ProgressToken { + /// `None` means "disable progress", never "fail the call": the pinned schema declares the token + /// as an opaque client value the receiver may simply ignore. + fn parse(value: &Value) -> Option { + match value { + Value::String(text) + if !text.is_empty() + && text.len() <= MAX_PROGRESS_TOKEN_LEN + && !text.chars().any(char::is_control) => + { + Some(Self::Text(text.clone())) + } + Value::Number(number) => Some(Self::Number(number.clone())), + _ => None, + } + } + + fn as_value(&self) -> Value { + match self { + Self::Text(text) => Value::String(text.clone()), + Self::Number(number) => Value::Number(number.clone()), + } + } +} + +/// The progress token of one request parameters object, already validated and bounded. The adapters +/// read the `_meta` object they already parsed ([`token_from_meta`]); this is the test seam of the +/// same rule. +#[cfg(test)] +pub(crate) fn progress_token(params: &Value) -> Option { + token_from_meta(params.get("_meta")) +} + +/// The validated token of one `RequestMetaObject`. A non-object `_meta` has no token. +pub(crate) fn token_from_meta(meta: Option<&Value>) -> Option { + meta.and_then(|meta| meta.get("progressToken")) + .and_then(ProgressToken::parse) +} + +/// One real, already reached execution step: the shared Tools service emits these at the stage +/// boundaries it actually crosses, so no percentage is invented and no timer drives them. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub(crate) enum Phase { + Resolved, + Authorized, + Dispatching, +} + +impl Phase { + const fn message(self) -> &'static str { + match self { + Self::Resolved => "tool_resolved", + Self::Authorized => "authorization_resolved", + Self::Dispatching => "execution_dispatched", + } + } +} + +#[derive(Clone, Debug)] +pub(crate) struct ProgressEvent { + progress: u64, + message: &'static str, +} + +/// The pinned `notifications/progress` frame. Both supported revisions declare the same parameters, +/// so the projection is shared; the token is echoed verbatim and never validated as a credential. +fn progress_frame(token: &ProgressToken, event: &ProgressEvent) -> Value { + json!({ + "jsonrpc": "2.0", + "method": "notifications/progress", + "params": { + "progressToken": token.as_value(), + "progress": event.progress, + "message": event.message, + } + }) +} + +#[derive(Clone)] +struct ProgressSink { + events: mpsc::Sender, + produced: Arc, +} + +impl ProgressSink { + fn emit(&self, message: &'static str) { + let progress = self + .produced + .fetch_add(1, std::sync::atomic::Ordering::SeqCst) + + 1; + let _ = self.events.try_send(ProgressEvent { progress, message }); + } +} + +/// A cooperative cancellation signal of one call. It is set at most once; a signal whose only sender +/// is gone simply never fires. +#[derive(Clone)] +pub(crate) struct CancelSignal { + receiver: watch::Receiver, +} + +impl CancelSignal { + fn never() -> Self { + let (_sender, receiver) = watch::channel(false); + Self { receiver } + } + + pub(crate) async fn cancelled(&mut self) { + if self + .receiver + .wait_for(|cancelled| *cancelled) + .await + .is_err() + { + // The owning call is gone, so nothing can cancel it any more. + std::future::pending::<()>().await; + } + } +} + +/// The request-scoped lifecycle of one `tools/call`: its progress sink (when the client asked for +/// progress *and* offered the stream carrier) and its cancellation signal. +#[derive(Clone)] +pub(crate) struct ToolCallLifecycle { + progress: Option, + cancel: CancelSignal, +} + +impl ToolCallLifecycle { + pub(crate) fn new( + token: Option, + ) -> (Self, Option>) { + match token { + Some(_) => { + let (sender, receiver) = mpsc::channel(PROGRESS_CAPACITY); + ( + Self { + progress: Some(ProgressSink { + events: sender, + produced: Arc::new(std::sync::atomic::AtomicU64::new(0)), + }), + cancel: CancelSignal::never(), + }, + Some(receiver), + ) + } + None => ( + Self { + progress: None, + cancel: CancelSignal::never(), + }, + None, + ), + } + } + + pub(crate) fn with_cancel(mut self, cancel: CancelSignal) -> Self { + self.cancel = cancel; + self + } + + /// Record one real execution step. Without a progress sink this is a no-op, so the shared service + /// does not branch on the presence of a token. + pub(crate) fn advance(&self, phase: Phase) { + if let Some(progress) = &self.progress { + progress.emit(phase.message()); + } + } + + pub(crate) fn cancelled(&mut self) -> impl Future + '_ { + self.cancel.cancelled() + } +} + +/// The owned identity of one call, so the call future can be driven by the response stream itself. +pub(crate) struct ToolCallRequest { + pub(crate) workspace_slug: String, + pub(crate) agent_slug: String, + pub(crate) credential: VerifiedMachineCredential, + pub(crate) correlation: CorrelationContext, + pub(crate) continuation: ContinuationSupport, + pub(crate) locale: ExecutionLocale, +} + +/// The wire facts the adapter owns: the envelope, the negotiated revision and response mode, the +/// validated token and — for the legacy revision — the session-scoped in-flight ownership. +pub(crate) struct ToolCallWire { + pub(crate) message: Value, + pub(crate) protocol_version: String, + pub(crate) response_mode: ResponseMode, + pub(crate) progress: Option, + pub(crate) session_id: Option, + pub(crate) in_flight: Option, +} + +/// Who owns a cancellable call. The session and the platform credential are the ownership of the +/// legacy revision; the progress token is deliberately not part of it. +#[derive(Clone, Debug, PartialEq, Eq)] +pub(crate) struct InFlightScope { + pub(crate) session_id: String, + pub(crate) owner: String, +} + +/// The bounded table of the calls a legacy client can still cancel. +pub(crate) struct InFlightCalls { + entries: Mutex>>, + capacity: usize, +} + +impl InFlightCalls { + pub(crate) fn new(capacity: usize) -> Self { + Self { + entries: Mutex::new(HashMap::new()), + capacity, + } + } + + fn entries(&self) -> std::sync::MutexGuard<'_, HashMap>> { + // A panic of another request must not make the cancellation table unusable. + self.entries + .lock() + .unwrap_or_else(|poisoned| poisoned.into_inner()) + } + + fn key(scope: &InFlightScope, request_id: &Value) -> String { + // The pinned `RequestId` is a string or a number; the two must not collapse into one key. + format!( + "{}\u{1f}{}\u{1f}{request_id}", + scope.session_id, scope.owner + ) + } + + /// Register one call as cancellable. `None` means the table is full (or the id is already live), + /// and the call then runs without cancellation instead of evicting someone else's entry. + pub(crate) fn register( + self: &Arc, + scope: &InFlightScope, + request_id: &Value, + ) -> Option { + let key = Self::key(scope, request_id); + let (sender, receiver) = watch::channel(false); + { + let mut entries = self.entries(); + if entries.len() >= self.capacity || entries.contains_key(&key) { + return None; + } + entries.insert(key.clone(), sender); + } + Some(InFlightEntry { + registry: Arc::clone(self), + key, + cancel: CancelSignal { receiver }, + }) + } + + /// Route one `notifications/cancelled` to the call it names. `false` means there is no such + /// in-flight call of this owner, which the specification requires to be ignored. + pub(crate) fn cancel(&self, scope: &InFlightScope, request_id: &Value) -> bool { + let entries = self.entries(); + entries + .get(&Self::key(scope, request_id)) + .is_some_and(|sender| sender.send(true).is_ok()) + } +} + +/// The live registration of one call: dropping it (terminal response, cancellation or a dropped +/// response stream) releases the table slot. +pub(crate) struct InFlightEntry { + registry: Arc, + key: String, + cancel: CancelSignal, +} + +impl InFlightEntry { + pub(crate) fn cancel_signal(&self) -> CancelSignal { + self.cancel.clone() + } +} + +impl Drop for InFlightEntry { + fn drop(&mut self) { + self.registry.entries().remove(&self.key); + } +} + +/// Run one `tools/call` through the shared Tools service with the lifecycle of this request. +/// +/// Without a progress token — or without the SSE carrier the client negotiated — the response is the +/// unchanged single JSON (or single-event SSE) response. With both, the response is the request's own +/// bounded stream: the real progress events of this call, then the terminal response as the last +/// event. Dropping that stream (a `2026-07-28` cancellation) or setting the signal of a legacy +/// `notifications/cancelled` drops the call future, which is the cooperative stop. +pub(crate) async fn run_tool_call( + state: Arc, + request: ToolCallRequest, + wire: ToolCallWire, + command: ToolCallCommand, +) -> Response { + // A token is only honoured when the client offered the only carrier a notification has: the + // request's own SSE stream. Otherwise the call runs unchanged (a receiver is never obligated). + let token = match (&wire.response_mode, &wire.progress) { + (ResponseMode::Sse, Some(token)) => Some(token.clone()), + _ => None, + }; + let (mut lifecycle, progress_events) = ToolCallLifecycle::new(token.clone()); + let in_flight = wire.in_flight.as_ref().and_then(|scope| { + let entry = state.in_flight.register(scope, &request_id(&wire.message)); + if let Some(entry) = &entry { + lifecycle = lifecycle.clone().with_cancel(entry.cancel_signal()); + } + entry + }); + + let message = wire.message.clone(); + let correlation = request.correlation.clone(); + let protocol_version = wire.protocol_version.clone(); + let response_mode = wire.response_mode; + + let mut call = Box::pin(call_future( + Arc::clone(&state), + request, + lifecycle.clone(), + command, + )); + + let Some(progress_events) = progress_events else { + // No notification carrier for this call: run it as before, still cancellable. + let outcome = tokio::select! { + biased; + outcome = &mut call => outcome, + _ = lifecycle.cancelled() => return cancelled_response(), + }; + return tool_command_response( + &message, + response_mode, + &protocol_version, + &correlation, + outcome, + ); + }; + + debug_assert!(matches!(response_mode, ResponseMode::Sse)); + let token = token.expect("a progress receiver implies a validated token"); + let stream = stream::unfold( + CallStream { + call, + events: progress_events, + cancel: lifecycle.cancel.clone(), + token, + message, + protocol_version: protocol_version.clone(), + correlation, + pending: VecDeque::new(), + finished: false, + logging: crate::protocol::carry_scope(), + _in_flight: in_flight, + }, + next_event, + ); + sse_response( + StatusCode::OK, + stream, + wire.session_id.as_deref(), + Some(&protocol_version), + ) +} + +async fn call_future( + state: Arc, + request: ToolCallRequest, + lifecycle: ToolCallLifecycle, + command: ToolCallCommand, +) -> ToolsOutcome { + handle_tools_command( + &state, + ServiceContext { + workspace_slug: &request.workspace_slug, + agent_slug: &request.agent_slug, + credential: &request.credential, + correlation: &request.correlation, + continuation: request.continuation, + locale: request.locale, + }, + ToolsCommand::Call(command), + Some(lifecycle), + ) + .await +} + +/// A cancelled call is not answered: the pinned rule for a cancelled request is that no further +/// message is sent for it, and the client that cancelled it ignores a late response anyway. Nothing +/// here claims that an outbound side effect did or did not happen — that statement belongs to the +/// Invocation History entry of the call, which records the cancellation as outcome-unknown. +fn cancelled_response() -> Response { + StatusCode::OK.into_response() +} + +struct CallStream { + call: Pin + Send>>, + events: mpsc::Receiver, + cancel: CancelSignal, + token: ProgressToken, + message: Value, + protocol_version: String, + correlation: CorrelationContext, + pending: VecDeque, + finished: bool, + /// The request's logging context, so the terminal event of the stream is projected exactly as the + /// single response of the same call would be (Story 3.18 carried across the stream, Story 3.4). + logging: crate::protocol::CarriedScope, + /// Held for the lifetime of the stream: the slot is released when the call is over, however it ends. + _in_flight: Option, +} + +enum Step { + Progress(ProgressEvent), + Outcome(ToolsOutcome), + Cancelled, +} + +/// One stream item: a queued frame, the next real progress event, the terminal response, or the end of +/// a cancelled stream. A cancelled call sends no terminal frame at all. +async fn next_event( + call: CallStream, +) -> Option<(Result, CallStream)> { + let scope = call.logging; + crate::protocol::in_carried_scope(scope, next_event_in_scope(call)).await +} + +async fn next_event_in_scope( + mut call: CallStream, +) -> Option<(Result, CallStream)> { + if let Some(frame) = call.pending.pop_front() { + return Some((Ok(frame), call)); + } + if call.finished { + return None; + } + + let step = { + let CallStream { + call, + events, + cancel, + .. + } = &mut call; + tokio::select! { + biased; + Some(event) = events.recv() => Step::Progress(event), + outcome = call => Step::Outcome(outcome), + _ = cancel.cancelled() => Step::Cancelled, + } + }; + + match step { + Step::Progress(event) => { + let frame = progress_frame(&call.token, &event); + Some((Ok(Event::default().data(frame.to_string())), call)) + } + Step::Outcome(outcome) => { + call.finished = true; + let payload = match tool_command_payload( + &call.message, + &call.protocol_version, + &call.correlation, + outcome, + ) { + ToolCommandPayload::Ok(payload) => payload, + ToolCommandPayload::Internal(_) => jsonrpc_internal_error(&call.message), + }; + // The same projection point the single response uses, so a streamed answer delivers the + // same closed `notifications/message` (Story 3.18) before its terminal frame. + crate::transport::note_logging_outcome(&payload); + for notification in crate::protocol::take_notifications() { + call.pending + .push_back(Event::default().data(notification.to_string())); + } + call.pending + .push_back(Event::default().data(payload.to_string())); + Some((Ok(call.pending.pop_front().expect("queued frame")), call)) + } + Step::Cancelled => { + call.finished = true; + call.pending.clear(); + None + } + } +} + +fn jsonrpc_internal_error(message: &Value) -> Value { + crate::jsonrpc::jsonrpc_error(request_id(message), -32603, "internal server error") +} + +#[cfg(test)] +#[path = "lifecycle_tests.rs"] +mod tests; diff --git a/crates/crank-community-mcp/src/app/lifecycle_tests.rs b/crates/crank-community-mcp/src/app/lifecycle_tests.rs new file mode 100644 index 0000000..681788d --- /dev/null +++ b/crates/crank-community-mcp/src/app/lifecycle_tests.rs @@ -0,0 +1,170 @@ +//! Story 3.4 bounds that do not need the HTTP surface: token validation, the monotonic bounded +//! progress queue, the pinned frame shape and the ownership of the in-flight cancellation table. + +use super::*; + +fn token(value: Value) -> Option { + progress_token(&json!({ "_meta": { "progressToken": value } })) +} + +#[test] +fn a_pinned_progress_token_is_a_bounded_string_or_a_number() { + assert_eq!( + token(json!("tok-1")), + Some(ProgressToken::Text("tok-1".to_owned())) + ); + assert!(matches!(token(json!(7)), Some(ProgressToken::Number(_)))); + assert!(matches!(token(json!(1.5)), Some(ProgressToken::Number(_)))); + + // Malformed and out-of-bound tokens disable progress instead of failing the call. + assert_eq!(token(json!("")), None); + assert_eq!(token(json!("x".repeat(MAX_PROGRESS_TOKEN_LEN + 1))), None); + assert_eq!(token(json!("line\nbreak")), None); + assert_eq!(token(json!(null)), None); + assert_eq!(token(json!(true)), None); + assert_eq!(token(json!({ "nested": 1 })), None); + assert_eq!(token(json!([1, 2])), None); + // A token at the bound is still accepted. + assert!(token(json!("x".repeat(MAX_PROGRESS_TOKEN_LEN))).is_some()); + // Absent `_meta`, absent token and a non-object `_meta` are all "no progress". + assert_eq!(progress_token(&json!({})), None); + assert_eq!(progress_token(&json!({ "_meta": { "other": 1 } })), None); + assert_eq!(progress_token(&json!({ "_meta": "not-an-object" })), None); +} + +#[tokio::test] +async fn real_steps_produce_strictly_increasing_bounded_progress_events() { + let (lifecycle, events) = ToolCallLifecycle::new(token(json!("tok-monotonic"))); + let mut events = events.expect("a validated token opens the progress queue"); + for phase in [Phase::Resolved, Phase::Authorized, Phase::Dispatching] { + lifecycle.advance(phase); + } + drop(lifecycle); + + let mut observed = Vec::new(); + while let Some(event) = events.recv().await { + observed.push((event.progress, event.message)); + } + assert_eq!( + observed, + vec![ + (1, "tool_resolved"), + (2, "authorization_resolved"), + (3, "execution_dispatched"), + ] + ); + assert!( + observed.windows(2).all(|pair| pair[0].0 < pair[1].0), + "progress must increase monotonically, got {observed:?}" + ); +} + +#[tokio::test] +async fn a_full_progress_queue_drops_events_instead_of_blocking_the_call() { + let (lifecycle, events) = ToolCallLifecycle::new(token(json!(9))); + let mut events = events.expect("a validated token opens the progress queue"); + // Many more steps than the queue holds: the call must never wait for the reader. + for _ in 0..(PROGRESS_CAPACITY * 4) { + lifecycle.advance(Phase::Resolved); + } + let mut delivered = 0; + while events.try_recv().is_ok() { + delivered += 1; + } + assert_eq!(delivered, PROGRESS_CAPACITY); +} + +#[tokio::test] +async fn without_a_token_no_progress_is_produced_at_all() { + let (lifecycle, events) = ToolCallLifecycle::new(None); + assert!(events.is_none()); + lifecycle.advance(Phase::Resolved); + lifecycle.advance(Phase::Dispatching); +} + +/// The pinned `notifications/progress` frame (schema `ProgressNotification`, both supported +/// revisions): `progressToken` echoed verbatim, `progress` increasing, `message` optional and +/// `total` absent because this server never invents one. +#[test] +fn the_progress_frame_matches_the_pinned_notification_shape() { + let event = ProgressEvent { + progress: 2, + message: Phase::Authorized.message(), + }; + assert_eq!( + progress_frame(&ProgressToken::Text("tok-2".to_owned()), &event), + json!({ + "jsonrpc": "2.0", + "method": "notifications/progress", + "params": { + "progressToken": "tok-2", + "progress": 2, + "message": "authorization_resolved" + } + }) + ); + assert_eq!( + progress_frame(&ProgressToken::Number(7.into()), &event)["params"]["progressToken"], + json!(7) + ); +} + +#[tokio::test] +async fn a_cancellation_only_reaches_the_call_of_the_same_session_and_credential() { + let registry = Arc::new(InFlightCalls::new(MAX_IN_FLIGHT_CALLS)); + let scope = InFlightScope { + session_id: "sess-1".to_owned(), + owner: "pk_a".to_owned(), + }; + let entry = registry + .register(&scope, &json!(42)) + .expect("the table has room"); + let mut signal = entry.cancel_signal(); + + // A foreign credential, a foreign session and a different request id cancel nothing. + for foreign in [ + InFlightScope { + session_id: "sess-1".to_owned(), + owner: "pk_b".to_owned(), + }, + InFlightScope { + session_id: "sess-2".to_owned(), + owner: "pk_a".to_owned(), + }, + ] { + assert!(!registry.cancel(&foreign, &json!(42))); + } + assert!(!registry.cancel(&scope, &json!(43))); + assert!( + tokio::time::timeout(std::time::Duration::from_millis(50), signal.cancelled()) + .await + .is_err(), + "a foreign cancellation must not fire the signal" + ); + + assert!(registry.cancel(&scope, &json!(42))); + tokio::time::timeout(std::time::Duration::from_millis(50), signal.cancelled()) + .await + .expect("the owner's cancellation fires the signal"); +} + +#[tokio::test] +async fn a_released_call_releases_its_slot_and_the_table_is_bounded() { + let registry = Arc::new(InFlightCalls::new(1)); + let scope = InFlightScope { + session_id: "sess-1".to_owned(), + owner: "pk_a".to_owned(), + }; + let entry = registry.register(&scope, &json!(1)).expect("first slot"); + assert!( + registry.register(&scope, &json!(2)).is_none(), + "the table refuses a call beyond its bound instead of evicting the live one" + ); + assert!(registry.cancel(&scope, &json!(1))); + drop(entry); + assert!( + !registry.cancel(&scope, &json!(1)), + "a terminal call is no longer cancellable" + ); + assert!(registry.register(&scope, &json!(2)).is_some()); +} diff --git a/crates/crank-community-mcp/src/app/request.rs b/crates/crank-community-mcp/src/app/request.rs index 9863ef8..34d8faa 100644 --- a/crates/crank-community-mcp/src/app/request.rs +++ b/crates/crank-community-mcp/src/app/request.rs @@ -14,6 +14,11 @@ pub(super) struct ToolCallParams { pub(super) name: String, #[serde(default, deserialize_with = "deserialize_arguments_object")] pub(super) arguments: Option, + /// Story 3.4: the pinned `RequestMetaObject` of this request. Only the validated + /// `progressToken` of it is read, and only to decide whether the client asked for out-of-band + /// progress; a malformed or foreign `_meta` never fails the call. + #[serde(default, rename = "_meta")] + pub(super) meta: Option, } /// The pinned `CallToolRequest.params.arguments` is an **optional object**. Omitting it stays valid diff --git a/crates/crank-community-mcp/src/app/response.rs b/crates/crank-community-mcp/src/app/response.rs index 8991c97..78733eb 100644 --- a/crates/crank-community-mcp/src/app/response.rs +++ b/crates/crank-community-mcp/src/app/response.rs @@ -23,71 +23,75 @@ pub(crate) fn take_confirmation_token(arguments: &mut Value) -> Option { .filter(|value| !value.trim().is_empty()) } -pub(crate) fn success_tool_response( +/// The era-neutral success payload of one `tools/call` (Story 3.4: the streamed response needs the +/// payload itself, because the terminal response is the last event of the request's stream). +pub(super) fn success_tool_payload( message: &Value, - response_mode: ResponseMode, protocol_version: &str, output: Value, -) -> Response { - transport_response( - StatusCode::OK, - jsonrpc_result( - request_id(message), - project_modern_result( - protocol_version, - json!({ - "content": [ - { - "type": "text", - "text": serde_json::to_string_pretty(&output).unwrap_or_else(|_| "{}".to_owned()) - } - ], - "structuredContent": output, - "isError": false - }), - ), +) -> Value { + jsonrpc_result( + request_id(message), + project_modern_result( + protocol_version, + json!({ + "content": [ + { + "type": "text", + "text": serde_json::to_string_pretty(&output).unwrap_or_else(|_| "{}".to_owned()) + } + ], + "structuredContent": output, + "isError": false + }), ), - response_mode, - None, - Some(protocol_version), ) } +#[cfg(test)] pub(crate) fn tool_error_response( message: &Value, response_mode: ResponseMode, protocol_version: &str, error: ToolErrorContract, ) -> Response { - let error_message = tool_error_text(&error); - let error_value = tool_error_value(&error); - transport_response( StatusCode::OK, - jsonrpc_result( - request_id(message), - project_modern_result( - protocol_version, - json!({ - "content": [ - { - "type": "text", - "text": error_message - } - ], - "structuredContent": { - "error": error_value - }, - "isError": true - }), - ), - ), + tool_error_payload(message, protocol_version, error), response_mode, None, Some(protocol_version), ) } +pub(super) fn tool_error_payload( + message: &Value, + protocol_version: &str, + error: ToolErrorContract, +) -> Value { + let error_message = tool_error_text(&error); + let error_value = tool_error_value(&error); + + jsonrpc_result( + request_id(message), + project_modern_result( + protocol_version, + json!({ + "content": [ + { + "type": "text", + "text": error_message + } + ], + "structuredContent": { + "error": error_value + }, + "isError": true + }), + ), + ) +} + /// The era-neutral `tools/list` result shape built from the shared command outcome. Object keys end /// up byte-lexicographically ordered, exactly as before the extraction. pub(super) fn tools_list_result(tools: Vec, next_cursor: Option) -> Value { @@ -193,28 +197,35 @@ pub(super) fn prompt_arguments_error_response( ) } -/// Map one shared Tools-command outcome back to the era-specific wire response (spec section 6.2). +/// One `tools/call` wire frame, or the adapter's own internal-error detail. /// -/// This adapter function is the only place that turns a neutral outcome into a response: the shared +/// Story 3.4: the same projection serves the single response and the terminal event of a streamed +/// response, so both forms of one outcome can never drift apart. +pub(super) enum ToolCommandPayload { + Ok(Value), + Internal(&'static str), +} + +/// Map one shared Tools-command outcome back to its era-specific wire payload (spec section 6.2). +/// +/// This adapter function is the only place that turns a neutral outcome into a wire value: the shared /// service never sees `ResponseMode`, the protocol revision, the request envelope or an /// `axum::Response`. `ApprovalPending` is a success for the client (it still has to answer), while /// an unavailable elicitation and a failing call keep their era-correct tool-error shape. -pub(super) fn tool_command_response( +pub(super) fn tool_command_payload( message: &Value, - response_mode: ResponseMode, protocol_version: &str, correlation: &CorrelationContext, outcome: ToolsOutcome, -) -> Response { +) -> ToolCommandPayload { match outcome { ToolsOutcome::Call(ToolCallOutcome::Completed(output)) | ToolsOutcome::Call(ToolCallOutcome::ApprovalPending(output)) => { - success_tool_response(message, response_mode, protocol_version, output) + ToolCommandPayload::Ok(success_tool_payload(message, protocol_version, output)) } ToolsOutcome::Call(ToolCallOutcome::ApprovalUnavailable(control_error)) => { - tool_error_response( + ToolCommandPayload::Ok(tool_error_payload( message, - response_mode, protocol_version, control_tool_error_contract( control_error, @@ -222,34 +233,49 @@ pub(super) fn tool_command_response( correlation.trace_id().as_str(), execution_locale(message), ), - ) + )) + } + ToolsOutcome::Call(ToolCallOutcome::InvalidParams(detail)) => { + ToolCommandPayload::Ok(jsonrpc_error(request_id(message), -32602, detail)) } - ToolsOutcome::Call(ToolCallOutcome::InvalidParams(detail)) => transport_response( - StatusCode::OK, - jsonrpc_error(request_id(message), -32602, detail), - response_mode, - None, - Some(protocol_version), - ), ToolsOutcome::Call(ToolCallOutcome::Error(contract)) => { - tool_error_response(message, response_mode, protocol_version, contract) + ToolCommandPayload::Ok(tool_error_payload(message, protocol_version, contract)) } // The pending approval could not be persisted: the adapter answers its internal error shape, // as the previous wire path did. - ToolsOutcome::Call(ToolCallOutcome::InternalFailure) => internal_jsonrpc_error( - message, - "the pending approval request could not be persisted", - ), + ToolsOutcome::Call(ToolCallOutcome::InternalFailure) => { + ToolCommandPayload::Internal("the pending approval request could not be persisted") + } // A call command never produces these variants; they are answered with the adapter's // internal error instead of being silently ignored. ToolsOutcome::List { .. } | ToolsOutcome::InvalidParams(_) | ToolsOutcome::CatalogUnavailable => { - internal_jsonrpc_error(message, "unexpected shared tools outcome for a tools/call") + ToolCommandPayload::Internal("unexpected shared tools outcome for a tools/call") } } } +/// The single-response form of [`tool_command_payload`]. +pub(super) fn tool_command_response( + message: &Value, + response_mode: ResponseMode, + protocol_version: &str, + correlation: &CorrelationContext, + outcome: ToolsOutcome, +) -> Response { + match tool_command_payload(message, protocol_version, correlation, outcome) { + ToolCommandPayload::Ok(payload) => transport_response( + StatusCode::OK, + payload, + response_mode, + None, + Some(protocol_version), + ), + ToolCommandPayload::Internal(detail) => internal_jsonrpc_error(message, detail), + } +} + pub(super) fn resource_error_response( message: &Value, response_mode: ResponseMode, diff --git a/crates/crank-community-mcp/src/protocol/command.rs b/crates/crank-community-mcp/src/protocol/command.rs index 7e52728..9b077bc 100644 --- a/crates/crank-community-mcp/src/protocol/command.rs +++ b/crates/crank-community-mcp/src/protocol/command.rs @@ -33,6 +33,7 @@ use crate::{ access::credential_allows_security_level, app::{ AppState, ApprovalPolicyContext, ApprovalPolicyDecision, InvocationRecord, + lifecycle::{Phase, ToolCallLifecycle}, maybe_handle_approval_policy, persist_invocation_for_key, resolve_generated_tool, resolve_operation_auth, runtime_operation, take_confirmation_token, }, @@ -140,10 +141,15 @@ pub(crate) enum ToolCallOutcome { /// Handle one shared Tools command. No wire envelope, `ResponseMode`, `axum::Response`, session or /// protocol revision crosses this boundary. +/// +/// `lifecycle` is the request-scoped progress/cancellation handle of a `tools/call` (Story 3.4); +/// a command that cannot have one (`tools/list`) passes `None`, and the service then simply never +/// produces a progress event. pub(crate) async fn handle_tools_command( state: &Arc, context: ServiceContext<'_>, command: ToolsCommand, + lifecycle: Option, ) -> ToolsOutcome { // One marker per entered owning Tools service/handler (Story 3.1 section 7.2). It is a // `#[cfg(test)]`-only, request-scoped counter and has no production effect. @@ -166,9 +172,9 @@ pub(crate) async fn handle_tools_command( Err(message) => ToolsOutcome::InvalidParams(message.to_owned()), } } - ToolsCommand::Call(call) => { - ToolsOutcome::Call(execute_tool_command(state, &context, call, &catalog).await) - } + ToolsCommand::Call(call) => ToolsOutcome::Call( + execute_tool_command(state, &context, call, &catalog, lifecycle.as_ref()).await, + ), } } @@ -178,6 +184,7 @@ async fn execute_tool_command( context: &ServiceContext<'_>, command: ToolCallCommand, catalog: &PublishedAgentCatalog, + lifecycle: Option<&ToolCallLifecycle>, ) -> ToolCallOutcome { match catalog.tool_selection_policy.mode { ToolAccessMode::Direct => { @@ -188,6 +195,7 @@ async fn execute_tool_command( &command.tool_name, command.arguments, command.confirmation_token, + lifecycle, ) .await } @@ -222,6 +230,7 @@ async fn execute_tool_command( &proxy.name, arguments, confirmation_token, + lifecycle, ) .await } @@ -240,6 +249,7 @@ async fn execute_resolved_tool( tool_name: &str, arguments: Value, confirmation_token: Option, + lifecycle: Option<&ToolCallLifecycle>, ) -> ToolCallOutcome { let correlation = context.correlation; let transport_request_id = correlation.request_id().as_str(); @@ -250,6 +260,10 @@ async fn execute_resolved_tool( Some(resolved) => { StageOutcome::Success.record(&resolve_span); drop(resolve_span); + // First real execution step: the addressed tool of the published catalog is resolved. + if let Some(lifecycle) = lifecycle { + lifecycle.advance(Phase::Resolved); + } resolved.tool } None => { @@ -349,8 +363,14 @@ async fn execute_resolved_tool( let resolved_auth = resolve_operation_auth(state, &tool.workspace_id, &operation.execution_config).await; + // A cancellation can only stop the call before it reaches its terminal outcome: nothing is + // persisted for a stopped call, so Invocation History can never claim a false `completed`. let result = match resolved_auth { Ok(resolved_auth) => { + // Second real step: the operation's own authorization is resolved, so the runtime may run. + if let Some(lifecycle) = lifecycle { + lifecycle.advance(Phase::Authorized); + } match RuntimeExecutionRequest::try_new( &tool.workspace_id, ExecutionOrigin::AgentSnapshot, @@ -365,7 +385,15 @@ async fn execute_resolved_tool( operation.execution_config.timeout_ms.max(1), ), ) { - Ok(request) => state.runtime.execute_outcome(request).await, + Ok(request) => { + // Third real step: the request is about to enter the runtime, so from here on an + // outbound side effect may happen and a cancellation can no longer promise that + // nothing was sent. + if let Some(lifecycle) = lifecycle { + lifecycle.advance(Phase::Dispatching); + } + state.runtime.execute_outcome(request).await + } Err(_) => Err(ExecutionFailure::new( ExecutionErrorCode::RuntimeInternal, correlation.clone(), diff --git a/crates/crank-community-mcp/src/protocol/logging.rs b/crates/crank-community-mcp/src/protocol/logging.rs index 25928e4..dae3743 100644 --- a/crates/crank-community-mcp/src/protocol/logging.rs +++ b/crates/crank-community-mcp/src/protocol/logging.rs @@ -192,6 +192,46 @@ pub(crate) fn set_active_level(level: Option) { }); } +/// The request's logging context, carried into a streamed response body (Story 3.4). +/// +/// A streamed `tools/call` response is assembled after the request handler returned, so its terminal +/// event would be projected outside the task-local scope of the request. This snapshot carries the +/// only two facts the projection needs — the level the client opted in to and whether the request +/// offered the SSE carrier — and never a request value. +#[derive(Clone, Copy, Default)] +pub(crate) struct CarriedScope { + active: Option, + sse_acceptable: bool, +} + +/// Snapshot the scope of the request that is being served now. Outside a scope the snapshot is +/// "not opted in", which delivers nothing. +pub(crate) fn carry_scope() -> CarriedScope { + REQUEST_LOG + .try_with(|log| { + let log = log.borrow(); + CarriedScope { + active: log.active, + sse_acceptable: log.sse_acceptable, + } + }) + .unwrap_or_default() +} + +/// Run one step of the streamed response inside a scope carrying the request's logging context. +pub(crate) async fn in_carried_scope(scope: CarriedScope, future: F) -> F::Output { + REQUEST_LOG + .scope( + RefCell::new(RequestLog { + active: scope.active, + sse_acceptable: scope.sse_acceptable, + pending: Vec::new(), + }), + future, + ) + .await +} + /// Remember that this request offered `text/event-stream`, the only carrier of a notification. pub(crate) fn set_sse_acceptable() { let _ = REQUEST_LOG.try_with(|log| { diff --git a/crates/crank-community-mcp/src/protocol/mod.rs b/crates/crank-community-mcp/src/protocol/mod.rs index b72d4dc..81e79c9 100644 --- a/crates/crank-community-mcp/src/protocol/mod.rs +++ b/crates/crank-community-mcp/src/protocol/mod.rs @@ -38,9 +38,10 @@ pub(crate) use command::{ }; pub(crate) use completion::{CompletionCommand, CompletionOutcome, handle_completion_command}; pub(crate) use logging::{ - EVENT_FAILED, EVENT_LEVEL_APPLIED, EVENT_REJECTED, EVENT_SERVED, INVALID_LEVEL, LogLevel, - LogLevelStore, LoggingOutcome, SetLevelCommand, handle_logging_command, modern_request_level, - note, scoped as logging_scope, set_active_level, set_sse_acceptable, take_notifications, + CarriedScope, EVENT_FAILED, EVENT_LEVEL_APPLIED, EVENT_REJECTED, EVENT_SERVED, INVALID_LEVEL, + LogLevel, LogLevelStore, LoggingOutcome, SetLevelCommand, carry_scope, handle_logging_command, + in_carried_scope, modern_request_level, note, scoped as logging_scope, set_active_level, + set_sse_acceptable, take_notifications, }; pub(crate) use prompts::{ PromptGetCommand, PromptsCommand, PromptsListCommand, PromptsOutcome, handle_prompts_command, diff --git a/crates/crank-community-mcp/src/protocol/registry.rs b/crates/crank-community-mcp/src/protocol/registry.rs index e031266..daf83d6 100644 --- a/crates/crank-community-mcp/src/protocol/registry.rs +++ b/crates/crank-community-mcp/src/protocol/registry.rs @@ -105,6 +105,10 @@ pub(crate) enum MethodHandler { Ping, Discover, Lifecycle, + /// `notifications/cancelled`: the legacy client cancels a `tools/call` it already issued + /// (Story 3.4). The handler only routes the id to the owner's in-flight call; it never widens + /// what may be cancelled and never authorizes by the progress token. + Cancelled, } #[derive(Clone, Copy, Debug)] @@ -599,6 +603,17 @@ pub(crate) const METHOD_DESCRIPTORS: &[MethodDescriptor] = &[ required_headers: HEADERS_NONE, handler: MethodHandler::Lifecycle, }, + MethodDescriptor { + // Story 3.4: the legacy revision's client-side cancellation of a request it issued. The + // pinned modern revision has no client-to-server notification over Streamable HTTP (closing + // the response stream is its cancellation signal), so this name exists in the legacy era + // only. It is a dispatch-only notification registration and advertises nothing. + name: "notifications/cancelled", + capability: CapabilityId::LegacyLifecycle, + kind: Kind::Notification, + required_headers: HEADERS_NONE, + handler: MethodHandler::Cancelled, + }, ]; #[cfg(test)] diff --git a/crates/crank-community-mcp/src/transport.rs b/crates/crank-community-mcp/src/transport.rs index d20c41a..57e59d0 100644 --- a/crates/crank-community-mcp/src/transport.rs +++ b/crates/crank-community-mcp/src/transport.rs @@ -313,7 +313,7 @@ pub(super) fn transport_response( /// Record the closed safe event of one response: served, rejected as invalid, failed, or a tool-level /// error. Every label is a fixed string of the closed vocabulary; nothing from the payload or the /// request is copied into it. -fn note_logging_outcome(payload: &Value) { +pub(super) fn note_logging_outcome(payload: &Value) { use crate::protocol::{EVENT_FAILED, EVENT_REJECTED, EVENT_SERVED, LogLevel, note}; if payload.get("error").is_some() { match payload.pointer("/error/code").and_then(Value::as_i64) { diff --git a/scripts/ci-story-checks.sh b/scripts/ci-story-checks.sh index 0c51a3a..90906f3 100755 --- a/scripts/ci-story-checks.sh +++ b/scripts/ci-story-checks.sh @@ -45,3 +45,11 @@ run_atdd "capability inventory projection" -p mcp-server --test integration inve # The advertisement projection is already covered by the `inventory_projection` entry above. run_atdd "Resource/Prompt change signals" -p mcp-server --test integration mcp_signals -- --test-threads=1 run_atdd "change signal wire oracles" -p crank-community-mcp --lib protocol::signals -- --test-threads=1 + +# Story 3.4 (FR-14): progress and cancellation of one synchronous tools/call, on both supported +# revisions. The lifecycle bounds (token vocabulary, monotonic bounded queue, pinned frame shape, +# cancellation ownership) are unit-level; the end-to-end behaviour (real progress stream, no token, +# malformed/oversized/reused token, owner/foreign/late cancellation, ambiguous outbound, client +# smoke) runs against the real endpoint, a real published catalog and a real counted upstream. +run_atdd "tool call lifecycle bounds" -p crank-community-mcp --lib app::lifecycle -- --test-threads=1 +run_atdd "tool call progress and cancellation" -p mcp-server --test integration tools_lifecycle -- --test-threads=1