Files
crank/crates/crank-community-mcp/src/protocol/command.rs
T
hermes_dev 862cde8559 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.
2026-10-26 12:02:11 +00:00

591 lines
23 KiB
Rust

//! Narrow shared Tools-service boundary (Story 3.1, decision D-4).
//!
//! Both protocol eras use the same Tools service: the adapters parse their wire form into a command,
//! build the verified context and map the neutral outcome back. The wire envelope, `ResponseMode`,
//! an `axum::Response`, the session carrier and the protocol revision never cross this boundary, and
//! the reserved `_crank_confirmation_token` marker is removed from the wire arguments by the adapter
//! (the `call_tool` proxy arm additionally removes the marker of its own nested arguments, exactly
//! as the previous shared implementation did).
//!
//! Advertisement is not per-call authorization: the credential security level check, the approval
//! policy, the runtime execution and the invocation history stay part of the shared service, and the
//! adapter is the only place that turns an outcome into an era-specific response.
//!
//! The proposed command shape carried a `catalog_revision` field; it is deliberately not adopted:
//! the adapter has no revision of its own to declare (it would need a second catalog read just to
//! duplicate the published revision), and the service checks the `call_tool` proxy's declared
//! revision against the single published catalog it already reads.
use std::{sync::Arc, time::Instant};
use crank_core::{
CorrelationContext, ExecutionErrorCode, ExecutionFailure, ExecutionLocale, ExecutionOrigin,
InvocationLevel, InvocationSource, InvocationStatus, ToolAccessMode,
};
use crank_registry::PublishedAgentCatalog;
use crank_runtime::{ExecutionAuthorization, RuntimeExecutionRequest, RuntimeRequestContext};
use crank_trace::{ErrorCategory, Stage, StageOutcome};
use serde::Deserialize;
use serde_json::Value;
use tracing::Instrument;
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,
},
auth::VerifiedMachineCredential,
manifest::{CALL_TOOL_NAME, SEARCH_TOOLS_NAME, catalog_tool_definitions},
tool_error::{
McpControlError, ToolErrorContract, control_tool_error_contract,
tool_error_contract_from_failure,
},
};
/// Era-neutral continuation capability of one Tools command.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum ContinuationSupport {
ElicitationSupported,
ElicitationUnsupported,
}
impl ContinuationSupport {
pub(crate) fn from_supported(supported: bool) -> Self {
if supported {
Self::ElicitationSupported
} else {
Self::ElicitationUnsupported
}
}
pub(crate) fn supports_elicitation(self) -> bool {
matches!(self, Self::ElicitationSupported)
}
}
/// Verified, era-neutral context of one shared Tools command.
///
/// `workspace_slug`/`agent_slug` address the published catalog; the credential, the correlation and
/// the continuation capability are the verified inputs of the tools/call arm. `locale` is the
/// adapter-derived presentation preference of the request: the service composes the neutral error
/// contract, but it never sees the envelope the preference was read from.
pub(crate) struct ServiceContext<'a> {
pub(crate) workspace_slug: &'a str,
pub(crate) agent_slug: &'a str,
pub(crate) credential: &'a VerifiedMachineCredential,
pub(crate) correlation: &'a CorrelationContext,
pub(crate) continuation: ContinuationSupport,
pub(crate) locale: ExecutionLocale,
}
/// Parameters of a `tools/list` command, already parsed by the adapter from the wire form.
#[derive(Debug, Default, Deserialize)]
pub(crate) struct ToolsListCommand {
#[serde(default)]
pub(crate) cursor: Option<String>,
#[serde(default)]
pub(crate) limit: Option<usize>,
}
/// Parameters of a `tools/call` command.
///
/// `arguments` is the domain-only (object-shape validated) payload of the addressed tool and the
/// confirmation marker has already been removed by the adapter.
pub(crate) struct ToolCallCommand {
pub(crate) tool_name: String,
pub(crate) arguments: Value,
pub(crate) confirmation_token: Option<String>,
}
/// A command the shared Tools service accepts.
pub(crate) enum ToolsCommand {
List(ToolsListCommand),
Call(ToolCallCommand),
}
/// A neutral outcome of a shared Tools command.
pub(crate) enum ToolsOutcome {
List {
tools: Vec<Value>,
next_cursor: Option<String>,
},
Call(ToolCallOutcome),
/// The requested page is not representable: the adapter answers era-correct invalid params.
InvalidParams(String),
/// The published catalog could not be read: the adapter answers its internal-error shape.
CatalogUnavailable,
}
/// A neutral outcome of one `tools/call`, never an `axum::Response`.
pub(crate) enum ToolCallOutcome {
/// The operation completed; the adapter turns the output into its success tool response.
Completed(Value),
/// The operation waits for a human decision; the adapter turns the payload into its success
/// tool response.
ApprovalPending(Value),
/// The required elicitation cannot be completed by this client; the adapter builds the
/// era-correct tool error contract.
ApprovalUnavailable(McpControlError),
/// The payload is not a valid command for this catalog; the adapter answers era-correct
/// invalid params.
InvalidParams(String),
/// A failing tool call; the adapter turns the contract into its error tool response.
Error(ToolErrorContract),
/// The service could not complete its own bookkeeping; the adapter answers its internal error
/// shape.
InternalFailure,
}
/// 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.
#[cfg(test)]
crate::app::dispatch_observer::tools_service_enter();
let catalog = match state
.catalog
.get_catalog(context.workspace_slug, context.agent_slug)
.await
{
Ok(catalog) => catalog,
Err(_error) => return ToolsOutcome::CatalogUnavailable,
};
match command {
ToolsCommand::List(list) => {
match paginate_tools_list(catalog_tool_definitions(&catalog), list) {
Ok((tools, next_cursor)) => ToolsOutcome::List { tools, next_cursor },
Err(message) => ToolsOutcome::InvalidParams(message.to_owned()),
}
}
ToolsCommand::Call(call) => ToolsOutcome::Call(
execute_tool_command(state, &context, call, &catalog, lifecycle.as_ref()).await,
),
}
}
/// The access-mode policy of the catalog decides what one `tools/call` command means.
async fn execute_tool_command(
state: &Arc<AppState>,
context: &ServiceContext<'_>,
command: ToolCallCommand,
catalog: &PublishedAgentCatalog,
lifecycle: Option<&ToolCallLifecycle>,
) -> ToolCallOutcome {
match catalog.tool_selection_policy.mode {
ToolAccessMode::Direct => {
execute_resolved_tool(
state,
context,
catalog,
&command.tool_name,
command.arguments,
command.confirmation_token,
lifecycle,
)
.await
}
ToolAccessMode::Search if command.tool_name == SEARCH_TOOLS_NAME => {
match crate::tool_search::search_tools_outcome(catalog, command.arguments) {
Ok(result) => ToolCallOutcome::Completed(result),
Err(detail) => ToolCallOutcome::InvalidParams(detail),
}
}
ToolAccessMode::Search if command.tool_name == CALL_TOOL_NAME => {
let proxy: ProxyToolCallArguments = match serde_json::from_value(command.arguments) {
Ok(proxy) => proxy,
Err(error) => return ToolCallOutcome::InvalidParams(error.to_string()),
};
if proxy.catalog_revision != catalog.catalog_revision {
return ToolCallOutcome::Error(control_tool_error_contract(
McpControlError::CatalogRevisionChanged,
context.correlation.request_id().as_str(),
context.correlation.trace_id().as_str(),
context.locale,
));
}
let mut arguments = proxy.arguments;
// The proxied call carries its own arguments: its marker is the one that belonged to
// that call, so it wins over the adapter-level marker of the proxy request itself.
let confirmation_token =
take_confirmation_token(&mut arguments).or(command.confirmation_token);
execute_resolved_tool(
state,
context,
catalog,
&proxy.name,
arguments,
confirmation_token,
lifecycle,
)
.await
}
ToolAccessMode::Search => {
ToolCallOutcome::InvalidParams(tool_not_found_text(&command.tool_name))
}
}
}
/// Resolve the owning tool of the addressed catalog, then run the real call: authorization, approval
/// policy, runtime execution and invocation history.
async fn execute_resolved_tool(
state: &Arc<AppState>,
context: &ServiceContext<'_>,
catalog: &PublishedAgentCatalog,
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();
let resolve_span = Stage::McpToolsResolve.span();
let resolved = resolve_span.in_scope(|| resolve_generated_tool(&catalog.tools, tool_name));
let tool = match resolved {
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 => {
StageOutcome::Error.record(&resolve_span);
ErrorCategory::Catalog.record(&resolve_span);
drop(resolve_span);
return ToolCallOutcome::InvalidParams(tool_not_found_text(tool_name));
}
};
let platform_api_key_id = context.credential.platform_api_key_id.clone();
if !credential_allows_security_level(context.credential, tool.operation.security_level) {
let failure =
ExecutionFailure::new(ExecutionErrorCode::AuthorizationDenied, correlation.clone());
persist_invocation_for_key(
state,
&tool,
platform_api_key_id.as_ref(),
InvocationRecord {
request_id: Some(transport_request_id),
trace_id: Some(correlation.trace_id().as_str()),
tool_name: &tool.tool_name,
status: InvocationStatus::Error,
level: InvocationLevel::Warn,
message: failure.error_code().as_str(),
status_code: None,
error_kind: Some(failure.error_code().as_str()),
execution_stage: Some(failure.stage()),
execution_error_code: Some(failure.error_code()),
retryability: Some(failure.retryability()),
outcome_certainty: Some(failure.outcome_certainty()),
duration: std::time::Duration::ZERO,
request_preview: crank_core::sanitize_invocation_preview(&arguments),
response_preview: Value::Null,
},
)
.await;
return ToolCallOutcome::Error(tool_error_contract_from_failure(&failure, context.locale));
}
let operation = runtime_operation(&tool);
if tool
.operation
.execution_config
.approval_policy
.as_ref()
.is_some_and(|policy| policy.required)
{
let approval_span = Stage::ApprovalCheck.span();
let decision = maybe_handle_approval_policy(ApprovalPolicyContext {
state,
tool: &tool,
arguments: &arguments,
platform_api_key_id: platform_api_key_id.as_ref(),
correlation,
continuation: context.continuation,
})
.instrument(approval_span.clone())
.await;
if let Some(decision) = decision {
return match decision {
ApprovalPolicyDecision::Pending(payload) => {
StageOutcome::Required.record(&approval_span);
ToolCallOutcome::ApprovalPending(payload)
}
ApprovalPolicyDecision::ElicitationUnavailable => {
StageOutcome::Error.record(&approval_span);
ErrorCategory::Approval.record(&approval_span);
ToolCallOutcome::ApprovalUnavailable(
McpControlError::ApprovalElicitationNotSupported,
)
}
ApprovalPolicyDecision::StorageFailed => {
StageOutcome::Error.record(&approval_span);
ErrorCategory::Approval.record(&approval_span);
ToolCallOutcome::InternalFailure
}
};
}
StageOutcome::Allowed.record(&approval_span);
}
let mut runtime_request_context = RuntimeRequestContext::from_correlation(correlation)
.with_response_cache_scope(
tool.workspace_id.as_str().to_owned(),
tool.agent_id.as_str().to_owned(),
)
.with_metering_context(
tool.workspace_id.clone(),
Some(tool.agent_id.clone()),
InvocationSource::AgentToolCall,
);
if let Some(token) = confirmation_token {
runtime_request_context = runtime_request_context.with_confirmation_token(token);
}
let started_at = Instant::now();
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,
Some(&tool.agent_id),
&operation,
&arguments,
ExecutionAuthorization::Authorized,
resolved_auth.as_ref(),
&runtime_request_context,
Instant::now()
+ std::time::Duration::from_millis(
operation.execution_config.timeout_ms.max(1),
),
) {
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(),
)),
}
}
Err(error) => Err(crank_runtime::normalize_runtime_error(&error, correlation)),
};
match result {
Ok(success) => {
let request_preview = success.request_preview;
let output = success.output;
persist_invocation_for_key(
state,
&tool,
platform_api_key_id.as_ref(),
InvocationRecord {
request_id: Some(transport_request_id),
trace_id: Some(correlation.trace_id().as_str()),
tool_name: &tool.tool_name,
status: InvocationStatus::Ok,
level: InvocationLevel::Info,
message: "agent tool call completed",
status_code: None,
error_kind: None,
execution_stage: Some(crank_core::ExecutionStage::Runtime),
execution_error_code: None,
retryability: Some(crank_core::Retryability::Never),
outcome_certainty: Some(crank_core::OutcomeCertainty::Certain),
duration: started_at.elapsed(),
request_preview,
response_preview: output.clone(),
},
)
.await;
ToolCallOutcome::Completed(output)
}
Err(failure) => {
persist_invocation_for_key(
state,
&tool,
platform_api_key_id.as_ref(),
InvocationRecord {
request_id: Some(transport_request_id),
trace_id: Some(correlation.trace_id().as_str()),
tool_name: &tool.tool_name,
status: InvocationStatus::Error,
level: InvocationLevel::Error,
message: failure.error_code().as_str(),
status_code: failure.upstream_status(),
error_kind: Some(failure.error_code().as_str()),
execution_stage: Some(failure.stage()),
execution_error_code: Some(failure.error_code()),
retryability: Some(failure.retryability()),
outcome_certainty: Some(failure.outcome_certainty()),
duration: started_at.elapsed(),
request_preview: Value::Null,
response_preview: Value::Null,
},
)
.await;
ToolCallOutcome::Error(tool_error_contract_from_failure(&failure, context.locale))
}
}
}
#[derive(Debug, Deserialize)]
struct ProxyToolCallArguments {
name: String,
#[serde(deserialize_with = "crate::protocol::deserialize_object_only")]
arguments: Value,
catalog_revision: String,
}
fn tool_not_found_text(tool_name: &str) -> String {
format!("tool {tool_name} was not found")
}
/// Pagination of the advertised tool definitions. Domain-only: it never sees the request envelope.
fn paginate_tools_list(
definitions: Vec<Value>,
command: ToolsListCommand,
) -> Result<(Vec<Value>, Option<String>), &'static str> {
const MAX_TOOLS_LIST_LIMIT: usize = 100;
let start = match command.cursor {
Some(cursor) if cursor.is_empty() => 0,
Some(cursor) => cursor
.parse::<usize>()
.map_err(|_| "invalid tools/list cursor")?,
None => 0,
};
if start > definitions.len() {
return Err("tools/list cursor is out of range");
}
let limit = command
.limit
.unwrap_or(definitions.len())
.clamp(1, MAX_TOOLS_LIST_LIMIT);
let end = start.saturating_add(limit).min(definitions.len());
let tools = definitions[start..end].to_vec();
let next_cursor = (end < definitions.len()).then(|| end.to_string());
Ok((tools, next_cursor))
}
#[cfg(test)]
mod tests {
use super::*;
use serde_json::json;
fn definitions(count: usize) -> Vec<Value> {
(0..count)
.map(|index| json!({"name": format!("tool-{index}")}))
.collect()
}
#[test]
fn first_page_reports_the_next_cursor_only_when_more_tools_remain() {
let (tools, next_cursor) =
paginate_tools_list(definitions(3), ToolsListCommand::default()).expect("valid page");
assert_eq!(tools.len(), 3);
assert_eq!(next_cursor, None);
}
#[test]
fn a_bounded_page_reports_the_following_cursor() {
let (tools, next_cursor) = paginate_tools_list(
definitions(5),
ToolsListCommand {
cursor: None,
limit: Some(2),
},
)
.expect("valid page");
assert_eq!(tools, definitions(2));
assert_eq!(next_cursor.as_deref(), Some("2"));
let (tools, next_cursor) = paginate_tools_list(
definitions(5),
ToolsListCommand {
cursor: Some("2".to_owned()),
limit: Some(2),
},
)
.expect("valid page");
assert_eq!(
tools,
vec![json!({"name": "tool-2"}), json!({"name": "tool-3"})]
);
assert_eq!(next_cursor.as_deref(), Some("4"));
}
#[test]
fn a_malformed_cursor_is_invalid_params_and_never_a_default_page() {
assert_eq!(
paginate_tools_list(
definitions(3),
ToolsListCommand {
cursor: Some("not-a-cursor".to_owned()),
limit: None,
},
)
.unwrap_err(),
"invalid tools/list cursor"
);
assert_eq!(
paginate_tools_list(
definitions(3),
ToolsListCommand {
cursor: Some("9".to_owned()),
limit: None,
},
)
.unwrap_err(),
"tools/list cursor is out of range"
);
}
#[test]
fn continuation_support_is_an_era_neutral_value_object() {
assert!(ContinuationSupport::from_supported(true).supports_elicitation());
assert!(!ContinuationSupport::from_supported(false).supports_elicitation());
}
#[test]
fn an_unknown_tool_name_is_reported_verbatim() {
assert_eq!(
tool_not_found_text("create_lead"),
"tool create_lead was not found"
);
}
}