Merge pull request 'MCP: execute completion through request-scoped SDK handler' (#138) from delivery/rmcp107-completion-handler into main
CI / UI Checks (push) Successful in 14s
CI / Rust Checks (push) Successful in 58m31s
CI / Rust Feature Validation (push) Skipped
CI / Frontend E2E (push) Skipped
CI / Community Image Smoke (push) Skipped
CI / Required Checks (push) Successful in 1s
CI / Deploy (push) Skipped
Community Release / release (push) Successful in 1h23m37s

This commit was merged in pull request #138.
This commit is contained in:
bsodfather committed 2026-11-13 14:12:04 +00:00
commit 5611e81579
8 files changed
+485 -40

No files matched your search

+1
View File
@@ -34,6 +34,7 @@ pub(crate) mod lifecycle;
mod metrics;
mod request;
mod response;
mod rmcp_completion;
mod rmcp_dispatch;
#[cfg(test)]
mod rmcp_http;
@@ -73,6 +73,8 @@ pub(crate) struct CounterSet {
sdk_prompts_get_result: AtomicUsize,
sdk_completion_dispatch: AtomicUsize,
sdk_completion_result: AtomicUsize,
sdk_completion_handler_completed: AtomicUsize,
sdk_completion_handler_consumed: AtomicUsize,
sdk_logging_dispatch: AtomicUsize,
sdk_logging_level: AtomicUsize,
sdk_logging_notification: AtomicUsize,
@@ -219,6 +221,12 @@ impl CounterSet {
pub(crate) fn sdk_completion_result(&self) -> usize {
self.sdk_completion_result.load(Ordering::SeqCst)
}
pub(crate) fn sdk_completion_handler_completed(&self) -> usize {
self.sdk_completion_handler_completed.load(Ordering::SeqCst)
}
pub(crate) fn sdk_completion_handler_consumed(&self) -> usize {
self.sdk_completion_handler_consumed.load(Ordering::SeqCst)
}
pub(crate) fn sdk_prompts_dispatch(&self) -> usize {
self.sdk_prompts_dispatch.load(Ordering::SeqCst)
}
@@ -459,10 +467,24 @@ pub(crate) fn sdk_completion_result_serialized() {
increment(|counters| &counters.sdk_completion_result);
}
/// Mark inside the ServerHandler override after domain await and typed Result construction.
pub(crate) fn sdk_completion_handler_completed() {
increment(|counters| &counters.sdk_completion_handler_completed);
}
/// Mark in the caller only after matching and consuming the actual trait Result.
pub(crate) fn sdk_completion_handler_consumed() {
increment(|counters| &counters.sdk_completion_handler_consumed);
}
#[cfg(test)]
#[path = "../rmcp_completion_runtime_tests.rs"]
mod rmcp_completion_runtime_tests;
#[cfg(test)]
#[path = "../rmcp_completion_handler_runtime_tests.rs"]
mod rmcp_completion_handler_runtime_tests;
/// Mark only after constructing the real SDK typed legacy logging request.
pub(crate) fn sdk_logging_dispatch_enter() {
increment(|counters| &counters.sdk_logging_dispatch);
@@ -0,0 +1,215 @@
//! Request-owned SDK completion handler; the domain future remains in its caller.
use std::sync::Arc;
use crank_core::{CorrelationContext, ExecutionLocale};
use rmcp::{ErrorData, RoleServer, ServerHandler, model::*, service::RequestContext};
use serde_json::{Map, Value};
use super::AppState;
use crate::{
auth::VerifiedMachineCredential,
protocol::{self, CompletionCommand, CompletionOutcome, CompletionReference, ServiceContext},
};
#[derive(Clone)]
struct Scope {
workspace: String,
agent: String,
credential: VerifiedMachineCredential,
correlation: CorrelationContext,
continuation: protocol::ContinuationSupport,
locale: ExecutionLocale,
revision: String,
context: Option<Map<String, Value>>,
}
impl Scope {
fn service(&self) -> ServiceContext<'_> {
ServiceContext {
workspace_slug: &self.workspace,
agent_slug: &self.agent,
credential: &self.credential,
correlation: &self.correlation,
continuation: self.continuation,
locale: self.locale,
}
}
}
#[derive(Clone)]
struct CompletionHandler {
state: Arc<AppState>,
#[cfg(test)]
domain: Option<Arc<tests::Domain>>,
}
fn internal() -> ErrorData {
ErrorData::internal_error("completion handler unavailable", None)
}
impl CompletionHandler {
async fn domain(&self, scope: &Scope, command: CompletionCommand) -> CompletionOutcome {
#[cfg(test)]
if let Some(domain) = &self.domain {
return domain.complete(command).await;
}
protocol::handle_completion_command(&self.state, scope.service(), &scope.revision, command)
.await
}
fn scope(context: &RequestContext<RoleServer>) -> Result<Scope, ErrorData> {
context
.extensions
.get::<Scope>()
.cloned()
.ok_or_else(internal)
}
async fn execute(
&self,
scope: &Scope,
params: CompleteRequestParams,
) -> Result<CompleteResult, ErrorData> {
let reference = match params.r#ref {
Reference::Prompt(prompt) => CompletionReference::Prompt { name: prompt.name },
Reference::Resource(resource) => CompletionReference::Resource { uri: resource.uri },
_ => {
return Err(ErrorData::invalid_params(
"invalid completion/complete parameters",
None,
));
}
};
// SDK context only accepts strings; retain the original JSON for domain validation.
let context = scope
.context
.clone()
.map(|arguments| serde_json::from_value(serde_json::json!({"arguments": arguments})))
.transpose()
.map_err(|_| internal())?;
let command = CompletionCommand {
reference,
argument: crate::protocol::CompletionArgument {
name: params.argument.name,
value: params.argument.value,
},
context,
};
match self.domain(scope, command).await {
CompletionOutcome::Completed {
values,
total,
has_more,
} => {
let mut info = CompletionInfo::new(values).map_err(|_| internal())?;
info.total = total.and_then(|v| u32::try_from(v).ok());
info.has_more = Some(has_more);
Ok(CompleteResult::new(info))
}
CompletionOutcome::InvalidParams(detail) => {
Err(ErrorData::invalid_params(detail, None))
}
CompletionOutcome::NotAvailable => Err(ErrorData::invalid_params(
"the completion reference is not available",
None,
)),
CompletionOutcome::CatalogUnavailable => Err(internal()),
}
}
}
impl ServerHandler for CompletionHandler {
async fn complete(
&self,
request: CompleteRequestParams,
context: RequestContext<RoleServer>,
) -> Result<CompleteResult, ErrorData> {
let scope = Self::scope(&context)?;
let result = self.execute(&scope, request).await;
#[cfg(test)]
super::dispatch_observer::sdk_completion_handler_completed();
result
}
}
async fn request_context(
handler: &CompletionHandler,
scope: Scope,
) -> Result<RequestContext<RoleServer>, ErrorData> {
let ping =
serde_json::from_value(serde_json::json!({"jsonrpc":"2.0", "id":1, "method":"ping"}))
.map_err(|_| internal())?;
let (transport, receiver) = rmcp::transport::OneshotTransport::<RoleServer>::new(ping);
let revision =
serde_json::from_value(Value::String(scope.revision.clone())).map_err(|_| internal())?;
let info = InitializeRequestParams::new(
ClientCapabilities::default(),
Implementation::new("crank-completion-context", "1"),
)
.with_protocol_version(revision);
let mut running = rmcp::service::serve_directly(handler.clone(), transport, Some(info));
let peer = running.peer().clone();
running.close().await.map_err(|_| internal())?;
drop(receiver);
let mut context = RequestContext::new(RequestId::Number(1), peer);
context.extensions.insert(scope);
Ok(context)
}
pub(super) async fn handle(
state: &Arc<AppState>,
context: ServiceContext<'_>,
revision: &str,
command: CompletionCommand,
) -> CompletionOutcome {
let (reference, context_args) = match command.reference {
CompletionReference::Prompt { name } => (
Reference::for_prompt(name),
command.context.and_then(|c| c.arguments),
),
CompletionReference::Resource { uri } => (
Reference::for_resource(uri),
command.context.and_then(|c| c.arguments),
),
};
let scope = Scope {
workspace: context.workspace_slug.to_owned(),
agent: context.agent_slug.to_owned(),
credential: context.credential.clone(),
correlation: context.correlation.clone(),
continuation: context.continuation,
locale: context.locale,
revision: revision.to_owned(),
context: context_args,
};
let handler = CompletionHandler {
state: state.clone(),
#[cfg(test)]
domain: None,
};
let sdk_context = match request_context(&handler, scope).await {
Ok(context) => context,
Err(_) => return CompletionOutcome::CatalogUnavailable,
};
#[cfg(test)]
super::dispatch_observer::sdk_completion_dispatch_enter();
let params = CompleteRequestParams::new(
reference,
ArgumentInfo::new(command.argument.name, command.argument.value),
);
let result = ServerHandler::complete(&handler, params, sdk_context).await;
restore(result)
}
fn restore(result: Result<CompleteResult, ErrorData>) -> CompletionOutcome {
let outcome = match result {
Ok(result) => CompletionOutcome::Completed {
values: result.completion.values,
total: result.completion.total.map(|v| v as usize),
has_more: result.completion.has_more.unwrap_or(false),
},
Err(error) if error.message == "the completion reference is not available" => {
CompletionOutcome::NotAvailable
}
Err(error) if error.code == ErrorCode::INVALID_PARAMS => {
CompletionOutcome::InvalidParams("invalid completion/complete parameters")
}
Err(_) => CompletionOutcome::CatalogUnavailable,
};
#[cfg(test)]
super::dispatch_observer::sdk_completion_handler_consumed();
outcome
}
#[cfg(test)]
#[path = "../rmcp_completion_handler_tests.rs"]
mod tests;
@@ -99,37 +99,5 @@ pub(super) async fn handle_completion_command(
revision: &str,
command: crate::protocol::CompletionCommand,
) -> crate::protocol::CompletionOutcome {
use crate::protocol::{
CompletionArgument, CompletionCommand, CompletionOutcome, CompletionReference,
};
use rmcp::model::{ArgumentInfo, CompleteRequestParams, Reference};
let reference = match command.reference {
CompletionReference::Prompt { name } => Reference::for_prompt(name),
CompletionReference::Resource { uri } => Reference::for_resource(uri),
};
let params = CompleteRequestParams::new(
reference,
ArgumentInfo::new(command.argument.name, command.argument.value),
);
// SDK context only supports strings; retain arbitrary JSON unchanged for domain validation.
let context_arguments = command.context;
#[cfg(test)]
super::dispatch_observer::sdk_completion_dispatch_enter();
let reference = match params.r#ref {
Reference::Prompt(reference) => CompletionReference::Prompt {
name: reference.name,
},
Reference::Resource(reference) => CompletionReference::Resource { uri: reference.uri },
_ => return CompletionOutcome::InvalidParams("invalid completion/complete parameters"),
};
let command = CompletionCommand {
reference,
argument: CompletionArgument {
name: params.argument.name,
value: params.argument.value,
},
context: context_arguments,
};
crate::protocol::handle_completion_command(state, context, revision, command).await
super::rmcp_completion::handle(state, context, revision, command).await
}
@@ -0,0 +1,30 @@
//! Completion actual ServerHandler execution/consumption observer oracle.
use super::{CounterSet, observe};
use std::sync::Arc;
pub(super) fn counts(c: &CounterSet) -> [usize; 2] {
[
c.sdk_completion_handler_completed(),
c.sdk_completion_handler_consumed(),
]
}
pub(super) fn delta(c: &CounterSet, before: [usize; 2]) -> ([usize; 2], [usize; 2]) {
let after = counts(c);
(std::array::from_fn(|i| after[i] - before[i]), [1, 1])
}
#[tokio::test]
async fn rmcp_completion_handler_observer_positive_control() {
use super::{sdk_completion_handler_completed, sdk_completion_handler_consumed};
let counters = Arc::new(CounterSet::default());
sdk_completion_handler_completed();
sdk_completion_handler_consumed();
assert_eq!(counts(&counters), [0, 0], "out-of-scope markers are no-ops");
observe(counters.clone(), async {
sdk_completion_handler_completed();
sdk_completion_handler_consumed();
})
.await;
assert_eq!(counts(&counters), [1, 1]);
}
@@ -0,0 +1,195 @@
//! Real trait execution, lossless request context, typed result consumption and drop ownership.
use super::*;
use serde_json::json;
use std::sync::{
Mutex,
atomic::{AtomicBool, AtomicUsize, Ordering::SeqCst},
};
#[derive(Default)]
pub(super) struct Domain {
outcome: Mutex<Option<CompletionOutcome>>,
calls: AtomicUsize,
pending: bool,
dropped: AtomicBool,
finished: AtomicBool,
}
struct DropWitness<'a>(&'a AtomicBool);
impl Drop for DropWitness<'_> {
fn drop(&mut self) {
self.0.store(true, SeqCst);
}
}
impl Domain {
pub(super) async fn complete(&self, command: CompletionCommand) -> CompletionOutcome {
self.calls.fetch_add(1, SeqCst);
assert!(
matches!(command.reference, CompletionReference::Resource { uri } if uri == "crank://bound/{region}")
);
assert_eq!(command.argument.name, "region");
assert_eq!(command.argument.value, "e");
assert_eq!(command.context.unwrap().arguments.unwrap(), args());
let _guard = DropWitness(&self.dropped);
if self.pending {
std::future::pending::<()>().await;
}
self.finished.store(true, SeqCst);
self.outcome
.lock()
.unwrap()
.take()
.expect("single domain execution")
}
}
fn args() -> Map<String, Value> {
json!({"number":42,"bool":true,"null":null,"array":["x"],"object":{"a":1}})
.as_object()
.unwrap()
.clone()
}
fn scope(revision: &str) -> Scope {
Scope {
workspace: "workspace".into(),
agent: "agent".into(),
credential: VerifiedMachineCredential {
machine_access_mode: crank_core::MachineAccessMode::StaticAgentKey,
max_security_level: crank_core::OperationSecurityLevel::Standard,
scopes: vec![crank_core::PlatformApiKeyScope::Read],
platform_api_key_id: Some("key".into()),
},
correlation: CorrelationContext::generate(),
continuation: protocol::ContinuationSupport::from_supported(false),
locale: ExecutionLocale::En,
revision: revision.into(),
context: Some(args()),
}
}
fn params() -> CompleteRequestParams {
CompleteRequestParams::new(
Reference::for_resource("crank://bound/{region}"),
ArgumentInfo::new("region", "e"),
)
}
async fn state() -> Arc<AppState> {
crank_test_support::postgres_schema_url_for_task("completion_handler_local", "t_7458fe3b")
.await;
super::super::rmcp_tools_tests::test_state().await
}
fn handler(state: &Arc<AppState>, outcome: CompletionOutcome, pending: bool) -> CompletionHandler {
CompletionHandler {
state: state.clone(),
domain: Some(Arc::new(Domain {
outcome: Mutex::new(Some(outcome)),
pending,
..Default::default()
})),
}
}
async fn context(h: &CompletionHandler, revision: &str) -> RequestContext<RoleServer> {
let c = request_context(h, scope(revision)).await.unwrap();
assert!(c.peer.is_transport_closed());
assert_eq!(
h.domain.as_ref().unwrap().calls.load(SeqCst),
0,
"bootstrap must not execute domain"
);
let s = CompletionHandler::scope(&c).unwrap();
assert_eq!(s.workspace, "workspace");
assert_eq!(s.agent, "agent");
assert_eq!(s.revision, revision);
assert_eq!(s.credential.platform_api_key_id.unwrap().as_str(), "key");
c
}
#[tokio::test]
async fn rmcp_completion_trait_result_is_consumed_and_domain_runs_once() {
let state = state().await;
for revision in ["2025-11-25", "2026-07-28"] {
let h = handler(
&state,
CompletionOutcome::Completed {
values: vec!["eu".into()],
total: Some(1),
has_more: false,
},
false,
);
let c = context(&h, revision).await;
let mut result = ServerHandler::complete(&h, params(), c).await.unwrap();
assert_eq!(result.completion.values, ["eu"]);
result.completion.values = vec!["typed".into()];
result.completion.total = None;
result.completion.has_more = Some(true);
match restore(Ok(result)) {
CompletionOutcome::Completed {
values,
total,
has_more,
} => {
assert_eq!(values, ["typed"]);
assert_eq!(total, None);
assert!(has_more);
}
_ => panic!("typed result not consumed"),
}
assert_eq!(h.domain.as_ref().unwrap().calls.load(SeqCst), 1);
let h = handler(
&state,
CompletionOutcome::Completed {
values: vec![],
total: None,
has_more: false,
},
false,
);
let c = context(&h, revision).await;
let result = ServerHandler::complete(&h, params(), c).await.unwrap();
assert!(result.completion.values.is_empty());
assert_eq!(result.completion.total, None);
}
}
#[tokio::test]
async fn rmcp_completion_dropping_trait_future_drops_pending_domain() {
let state = state().await;
for revision in ["2025-11-25", "2026-07-28"] {
let h = handler(&state, CompletionOutcome::CatalogUnavailable, true);
let c = context(&h, revision).await;
let domain = h.domain.as_ref().unwrap();
let mut future = Box::pin(ServerHandler::complete(&h, params(), c));
assert!(futures_util::poll!(&mut future).is_pending());
assert_eq!(domain.calls.load(SeqCst), 1);
assert!(!domain.dropped.load(SeqCst));
drop(future);
assert!(domain.dropped.load(SeqCst));
tokio::task::yield_now().await;
assert!(!domain.finished.load(SeqCst));
assert_eq!(domain.calls.load(SeqCst), 1);
}
}
#[tokio::test]
async fn rmcp_completion_trait_errors_remain_safe() {
let state = state().await;
for outcome in [
CompletionOutcome::InvalidParams("invalid completion/complete parameters"),
CompletionOutcome::NotAvailable,
CompletionOutcome::CatalogUnavailable,
] {
let h = handler(&state, outcome, false);
let c = context(&h, "2026-07-28").await;
let result = ServerHandler::complete(&h, params(), c).await;
assert!(result.is_err());
let error = result.as_ref().unwrap_err();
assert!(!error.to_string().contains("crank://bound"));
match error.code {
ErrorCode::INVALID_PARAMS => assert!(matches!(
restore(result),
CompletionOutcome::InvalidParams(_) | CompletionOutcome::NotAvailable
)),
ErrorCode::INTERNAL_ERROR => assert!(matches!(
restore(result),
CompletionOutcome::CatalogUnavailable
)),
_ => panic!("unexpected error"),
}
assert_eq!(h.domain.as_ref().unwrap().calls.load(SeqCst), 1);
}
}
@@ -6,6 +6,7 @@ use serde_json::{Value, json};
use std::{sync::Arc, time::Duration};
#[path = "rmcp_completion_test_support.rs"]
mod fixtures;
use super::rmcp_completion_handler_runtime_tests as handler;
use fixtures::{BOUNDED_URI, Endpoint, LARGE_URI, URI};
fn observe_body(response: Response, counters: Arc<CounterSet>) -> Response {
@@ -89,8 +90,10 @@ async fn success(
session: Option<&str>,
p: Value,
sse: bool,
require_handler: bool,
) -> (Value, [usize; 2]) {
let before = counts(&h.counters);
let handler_before = handler::counts(&h.counters);
let body = wire(
h.post(revision, session, &request(revision, p), sse).await,
sse,
@@ -107,12 +110,19 @@ async fn success(
assert!(result.get(key).is_none(), "{body}");
}
let after = counts(&h.counters);
let handler_delta = handler::delta(&h.counters, handler_before);
if require_handler {
assert_eq!(
handler_delta.0, handler_delta.1,
"actual completion handler execution/consumption: {handler_delta:?}"
);
}
(
result["completion"].clone(),
std::array::from_fn(|i| after[i] - before[i]),
)
}
async fn control(revision: &str) -> Vec<[usize; 2]> {
async fn control(revision: &str, require_handler: bool) -> Vec<[usize; 2]> {
let h = Endpoint::started().await;
let session = h.session(revision).await;
let session = session.as_deref();
@@ -149,7 +159,7 @@ async fn control(revision: &str) -> Vec<[usize; 2]> {
json!({"values":[],"total":0}),
),
] {
let (completion, delta) = success(&h, revision, session, p, sse).await;
let (completion, delta) = success(&h, revision, session, p, sse, require_handler).await;
assert_eq!(completion, expected);
deltas.push(delta);
}
@@ -160,6 +170,7 @@ async fn control(revision: &str) -> Vec<[usize; 2]> {
session,
params(resource(uri), "region", "item"),
sse,
require_handler,
)
.await;
assert_eq!(
@@ -179,7 +190,8 @@ async fn control(revision: &str) -> Vec<[usize; 2]> {
}
let mut with_context = params(prompt("greeting"), "tone", "w");
with_context["context"] = json!({"arguments":{"name":"Ada","tone":"dry"}});
let (completion, delta) = success(&h, revision, session, with_context, sse).await;
let (completion, delta) =
success(&h, revision, session, with_context, sse, require_handler).await;
assert_eq!(completion, json!({"values":["warm"],"total":1}));
deltas.push(delta);
let mut unavailable = None;
@@ -284,15 +296,15 @@ async fn control(revision: &str) -> Vec<[usize; 2]> {
}
#[tokio::test]
async fn rmcp_completion_wire_legacy() {
control(LEGACY_REVISION).await;
control(LEGACY_REVISION, false).await;
}
#[tokio::test]
async fn rmcp_completion_wire_modern() {
control(MODERN_REVISION).await;
control(MODERN_REVISION, false).await;
}
#[tokio::test]
async fn rmcp_completion_sdk_legacy() {
let deltas = control(LEGACY_REVISION).await;
let deltas = control(LEGACY_REVISION, true).await;
assert!(
deltas.iter().all(|d| *d == [1, 1]),
"SDK typed dispatch/result missing after successful HTTP: {deltas:?}"
@@ -300,7 +312,7 @@ async fn rmcp_completion_sdk_legacy() {
}
#[tokio::test]
async fn rmcp_completion_sdk_modern() {
let deltas = control(MODERN_REVISION).await;
let deltas = control(MODERN_REVISION, true).await;
assert!(
deltas.iter().all(|d| *d == [1, 1]),
"SDK typed dispatch/result missing after successful HTTP: {deltas:?}"
+2
View File
@@ -59,6 +59,8 @@ Inbound-response-срез #107 на базе rc.31/rmcp3.9.0 подключае
Prompts handler-срез #107 на базе rc.33 заменяет прежний DTO-only shim настоящими `ServerHandler::list_prompts/get_prompt` в `app/rmcp_prompts.rs`. Уже подключённый потребитель — `build_app` → обе HTTP dispatch-ветки → `rmcp_dispatch::handle_prompts_command`. Overrides напрямую await-ят прежний domain service ровно один раз; caller потребляет actual typed SDK Result, а request-local projection восстанавливает только непредставимые поля/omissions. Инертный ping-bootstrap закрывается до domain execution; domain future остаётся в parent HTTP future и отменяется при drop. Closed Peer не поддерживает callbacks. HTTP handler completed/consumed ATDD обеих revisions и trait-result mutation/drop regressions подтверждают реальное исполнение, прежние wire/access/error boundaries и lossless content; affected Prompts integration проверяет pinned static/dynamic Resource composition и dependency errors. Domain/auth/storage/session/transport не меняются. Это не завершение #107, feature qualification или разрешение #108/4.7/production.
Completion handler-срез #107 на базе rc.34 заменяет DTO-only completion shim настоящим `ServerHandler::complete` в `app/rmcp_completion.rs`. Подключённый потребитель — обе штатные HTTP dispatch-ветки через `rmcp_dispatch::handle_completion_command`. Override напрямую await-ит прежний domain service один раз; caller потребляет возвращённый SDK `CompleteResult`/`ErrorData`, сохраняя прежнюю JSON/SSE проекцию. Исходный JSON context передаётся request-local без сужения до SDK string map. Инертный ping-bootstrap закрывается до domain execution; drop parent future отменяет незавершённый domain future, закрытый Peer не поддерживает callbacks. Отдельные HTTP handler-completed/caller-consumed oracles и trait mutation/drop/error regressions проверяют этот переход, а wire controls сохраняют refs, published/archive binding, bounded/empty/omitted totals, safe errors и revocation. Domain/auth/storage/session/transport/capabilities не меняются. Полный #107, нагрузочная квалификация, #108/4.7 и production не завершены и не запускаются.
Проверяемый результат:
- Через SDK проходят действующие Tools, Resources, Prompts, completion, уведомления и подписки в применимых revisions, а также progress/cancel и существующая logging policy.