feat(epic3): progress и безопасная отмена Tool calls (Story 3.4, FR-14)
- request-scoped lifecycle одного tools/call: валидированный `_meta.progressToken` (строковый/числовой, 1..=128 байт) и bounded очередь реальных этапов (tool_resolved → authorization_resolved → execution_dispatched) в собственный SSE-stream запроса; без token или без stream-carrier результат не меняется; - сериализация `notifications/progress` по pinned схеме обеих revisions (progressToken/progress/message, total не изобретается); - отмена по revision: 2025-11-25 — `notifications/cancelled` через bounded in-flight таблицу (владение = session + platform credential, не progress token); 2026-07-28 — закрытие response stream; в обоих случаях drop будущего вызова = кооперативная остановка, terminal-сообщение не отправляется; - streamed ответ сохраняет проекцию Story 3.18: closed `notifications/message` перед финальным кадром (перенос logging-scope в тело стрима); - ATDD: 12 end-to-end тестов на реальном endpoint/каталоге/counted upstream (обе revisions, malformed/oversized/reused token, owner/foreign/late cancel, disconnect, ambiguous outbound, representative client smoke) + 7 unit-тестов границ lifecycle; entry в scripts/ci-story-checks.sh.
This commit is contained in:
1 parent
49c8af24ed
commit
862cde8559
18 files changed
+2207
-112
No files matched your search
@@ -14,5 +14,6 @@ mod integration {
|
||||
mod revision_matrix;
|
||||
mod static_resources;
|
||||
mod tool_search;
|
||||
mod tools_lifecycle;
|
||||
mod transport_protocol;
|
||||
}
|
||||
@@ -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;
|
||||
|
||||
|
||||
@@ -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<AtomicUsize>,
|
||||
completed: Arc<AtomicUsize>,
|
||||
}
|
||||
|
||||
/// 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<Value>| {
|
||||
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<Value>,
|
||||
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<Value>, 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<crank_core::InvocationLog> {
|
||||
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<u64> {
|
||||
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;
|
||||
@@ -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:?}"
|
||||
);
|
||||
}
|
||||
@@ -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::<Value>().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" })
|
||||
);
|
||||
}
|
||||
@@ -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<crate::protocol::StreamRegistry>,
|
||||
/// Story 3.4: the bounded table of the `tools/call` requests a legacy client can still cancel.
|
||||
pub(super) in_flight: Arc<self::lifecycle::InFlightCalls>,
|
||||
}
|
||||
|
||||
#[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));
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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<AppState>,
|
||||
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()
|
||||
}
|
||||
@@ -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<Self> {
|
||||
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<ProgressToken> {
|
||||
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<ProgressToken> {
|
||||
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<ProgressEvent>,
|
||||
produced: Arc<std::sync::atomic::AtomicU64>,
|
||||
}
|
||||
|
||||
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<bool>,
|
||||
}
|
||||
|
||||
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<ProgressSink>,
|
||||
cancel: CancelSignal,
|
||||
}
|
||||
|
||||
impl ToolCallLifecycle {
|
||||
pub(crate) fn new(
|
||||
token: Option<ProgressToken>,
|
||||
) -> (Self, Option<mpsc::Receiver<ProgressEvent>>) {
|
||||
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<Output = ()> + '_ {
|
||||
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<ProgressToken>,
|
||||
pub(crate) session_id: Option<String>,
|
||||
pub(crate) in_flight: Option<InFlightScope>,
|
||||
}
|
||||
|
||||
/// 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<HashMap<String, watch::Sender<bool>>>,
|
||||
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<String, watch::Sender<bool>>> {
|
||||
// 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<Self>,
|
||||
scope: &InFlightScope,
|
||||
request_id: &Value,
|
||||
) -> Option<InFlightEntry> {
|
||||
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<InFlightCalls>,
|
||||
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<AppState>,
|
||||
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<AppState>,
|
||||
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<Box<dyn Future<Output = ToolsOutcome> + Send>>,
|
||||
events: mpsc::Receiver<ProgressEvent>,
|
||||
cancel: CancelSignal,
|
||||
token: ProgressToken,
|
||||
message: Value,
|
||||
protocol_version: String,
|
||||
correlation: CorrelationContext,
|
||||
pending: VecDeque<Event>,
|
||||
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<InFlightEntry>,
|
||||
}
|
||||
|
||||
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<Event, std::convert::Infallible>, 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<Event, std::convert::Infallible>, 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;
|
||||
@@ -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<ProgressToken> {
|
||||
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());
|
||||
}
|
||||
@@ -14,6 +14,11 @@ pub(super) struct ToolCallParams {
|
||||
pub(super) name: String,
|
||||
#[serde(default, deserialize_with = "deserialize_arguments_object")]
|
||||
pub(super) arguments: Option<Value>,
|
||||
/// 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<Value>,
|
||||
}
|
||||
|
||||
/// The pinned `CallToolRequest.params.arguments` is an **optional object**. Omitting it stays valid
|
||||
|
||||
@@ -23,71 +23,75 @@ pub(crate) fn take_confirmation_token(arguments: &mut Value) -> Option<String> {
|
||||
.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<Value>, next_cursor: Option<String>) -> 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,
|
||||
|
||||
@@ -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<AppState>,
|
||||
context: ServiceContext<'_>,
|
||||
command: ToolsCommand,
|
||||
lifecycle: Option<ToolCallLifecycle>,
|
||||
) -> 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<String>,
|
||||
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(),
|
||||
|
||||
@@ -192,6 +192,46 @@ pub(crate) fn set_active_level(level: Option<LogLevel>) {
|
||||
});
|
||||
}
|
||||
|
||||
/// 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<LogLevel>,
|
||||
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<F: Future>(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| {
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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)]
|
||||
|
||||
@@ -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) {
|
||||
|
||||
@@ -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
|
||||
Reference in new issue
Block a user