Compare commits

...
Author SHA1 Message Date
bsodfather 44774883a0 fix(epic3): выводить Tools-сигнал из клиентской проекции tools/list (Story 3.5, FR-14)
CI / UI Checks (pull_request) Successful in 8s
CI / Rust Checks (pull_request) Successful in 10m49s
CI / Rust Feature Validation (pull_request) Skipped
CI / Frontend E2E (pull_request) Skipped
CI / Community Image Smoke (pull_request) Skipped
CI / Required Checks (pull_request) Successful in 1s
CI / Deploy (pull_request) Skipped
Community Release / release (push) Successful in 25m35s
QA F1: CatalogFingerprint сравнивал только Tool-bindings, а tools/list
строится из catalog_tool_definitions, которая ещё зависит от
tool_selection_policy (mode, groups, search.max_results); в Search-режиме
отдаваемый список вообще не зависит от bindings. Из-за этого commit,
меняющий только политику, не порождал notifications/tools/list_changed
(клиент оставался со stale-каталогом), а binding-only commit в Search
порождал ложный сигнал.

Теперь Tools-часть отпечатка — канонизированные определения, которые
реально отдаёт tools/list (отсортированы, чтобы порядок чтения не был
ложным изменением): сигнал есть ровно тогда, когда меняется видимая
клиенту проекция.

ATDD: новый сценарий на обеих ревизиях — policy-only commit (Direct ->
Search) даёт ровно один Tools-кадр и авторитетный tools/list с
search_tools/call_tool, а последующий binding-only commit в Search-режиме
не сигналит. Юнит-оракулы переведены на реальную проекцию: policy-only
change, невидимое поле политики, version bump с идентичным определением и
binding change в Search-режиме — silent.
2026-10-26 17:22:07 +00:00
hermes-dev a0365bb80b feat(epic3): отправлять Tools catalog change signals после commit (Story 3.5, FR-14)
Клиент, согласовавший tools list-changed, получает bounded
`notifications/tools/list_changed` после коммита видимой Tool-проекции
опубликованного Agent snapshot; `tools/list` остаётся авторитетным для
клиента без notification и после reconnect.

- signals.rs: третий тип сигнала в существующем stream-local watcher
  (один tick = максимум один кадр на тип, fixed-capacity queue, без
  cross-process bus и без post-commit hook); fingerprint сравнивает
  tool_name/operation.version/title/description, поэтому Tool-only
  commit не даёт Resource/Prompt сигналов и наоборот.
- registry.rs: tools.listChanged=true (реально отправляется в обеих
  revision); modern filter toolsListChanged теперь подтверждается
  acknowledge и не шлётся вне согласованного набора.
- legacy GET-стрим несёт Tools-сигнал вместе с Resource/Prompt.
- ATDD: RED на baseline (ack пуст, Tools-кадра нет, capability false),
  GREEN — 8 integration-сценариев × обе revision, unit-оракулы wire,
  representatives official MCP SDK 1.32.2 smoke со штатными headers.
- capability inventory/baseline manifest и frozen projection обновлены
  под tools.listChanged=true; ci-story-checks.sh дополнен AC 3.5.
2026-10-26 17:22:07 +00:00
bsodfather 2499016dc7 fix(epic3): принимать поток progress при JSON-first Accept официального SDK (Story 3.4, FR-14)
CI / Rust Checks (pull_request) Successful in 9m12s
CI / Rust Feature Validation (pull_request) Skipped
CI / Frontend E2E (pull_request) Skipped
CI / Community Image Smoke (pull_request) Skipped
CI / Required Checks (pull_request) Successful in 1s
CI / Deploy (pull_request) Skipped
CI / UI Checks (pull_request) Successful in 10s
Community Release / release (push) Successful in 24m39s
Официальный MCP SDK перечисляет медиатипы в `Accept` JSON-first
(`application/json, text/event-stream`). Прежняя реализация выбирала
negotiated JSON-тело, и клиент, которому нужен progress, не получал
ни одного кадра.

Коррекция переиспользует уже провалидированные шаги: для `tools/call`
с допустимым progress token и предложенным event-stream режим ответа
переключается на SSE. Admission/авторизация не двигались; другой метод,
отсутствующий или непригодный token и JSON-only `Accept` сохраняют
negotiated режим.

ATDD: тот же JSON-first `Accept` даёт строго монотонные progress 1/2/3 и
прежний result в обеих supported revisions, а негативные контроли
(без token и с непригодным token) остаются на JSON-теле.
2026-10-26 16:03:48 +00:00
bsodfather f613250fd3 fix(epic3): сделать ATDD отмены чувствительным к регрессии и покрыть bounds токена в обеих revision (Story 3.4, FR-14)
- CANCEL_GRACE_MS 1200 -> 2500 (> LONG_HOLD_MS) и const-assert на этот порядок:
  при незавершённой отмене вызов успевает завершиться и записать исход внутри
  окна проверки, поэтому тест доказывает остановку, а не только «ещё не готово».
- malformed/oversized/empty/object/array token теперь проверяются и в modern
  revision, не только в legacy (обе читают одно поле RequestMetaObject).
- комментарий cancelled_response приведён к фактическому поведению: у
  остановленного вызова строки Invocation History нет вообще.
2026-10-26 13:07:14 +00:00
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
33 changed files with 3349 additions and 209 deletions

No files matched your search

+1
View File
@@ -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;
@@ -20,7 +20,8 @@ use std::{
use axum::http::header;
use crank_artifacts::ArtifactStore;
use crank_core::{
Agent, AgentId, AgentStatus, AgentVersion, PlatformApiKeyScope, ToolSelectionPolicy,
Agent, AgentId, AgentStatus, AgentVersion, PlatformApiKeyScope, ToolAccessMode, ToolGroup,
ToolSearchSettings, ToolSelectionPolicy,
ids::{PromptId, ResourceId},
prompt::{PromptDefinition, PromptSensitivity},
};
@@ -47,10 +48,13 @@ const META_CLIENT_INFO: &str = "io.modelcontextprotocol/clientInfo";
const RESOURCE_LIST_CHANGED: &str = "notifications/resources/list_changed";
const PROMPT_LIST_CHANGED: &str = "notifications/prompts/list_changed";
const TOOL_LIST_CHANGED: &str = "notifications/tools/list_changed";
const SUBSCRIPTIONS_ACKNOWLEDGED: &str = "notifications/subscriptions/acknowledged";
const SUBSCRIPTION_ID_KEY: &str = "io.modelcontextprotocol/subscriptionId";
const AGENT_SLUG: &str = "sales-signals";
/// A second published Agent of the same workspace: its catalog must never reach another Agent.
const OTHER_AGENT_SLUG: &str = "sales-other";
static NEXT_ROOT: AtomicU64 = AtomicU64::new(0);
@@ -254,6 +258,26 @@ impl SignalsEndpoint {
tool_bindings: &[crank_core::AgentOperationBinding],
resource_bindings: &[AgentResourceBinding],
prompt_bindings: &[AgentPromptBinding],
) {
self.configure_draft_with_policy(
version,
tool_bindings,
&ToolSelectionPolicy::default(),
resource_bindings,
prompt_bindings,
)
.await;
}
/// The same transition with an explicit Tool selection policy (Story 3.5: the policy is part of
/// the served `tools/list` projection).
async fn configure_draft_with_policy(
&self,
version: u32,
tool_bindings: &[crank_core::AgentOperationBinding],
tool_selection_policy: &ToolSelectionPolicy,
resource_bindings: &[AgentResourceBinding],
prompt_bindings: &[AgentPromptBinding],
) {
self.registry
.save_agent_catalog_config_editable_with_prompts(
@@ -262,7 +286,7 @@ impl SignalsEndpoint {
agent_id: &self.agent_id,
agent_version: version,
bindings: tool_bindings,
tool_selection_policy: &ToolSelectionPolicy::default(),
tool_selection_policy,
resource_bindings,
expected_state: None,
},
@@ -410,6 +434,169 @@ impl SignalsEndpoint {
)
.await;
}
/// The reverse Tool-only commit: the second Tool binding leaves the published snapshot while the
/// visible Resource/Prompt projection stays identical.
async fn commit_tool_only_revert(&self) {
let version = self.next_draft_version().await;
self.open_draft(version).await;
self.configure_draft(
version,
&self.tool_bindings(),
&[self.notice_binding()],
&self.extended_prompts(),
)
.await;
self.publish_version(version).await;
}
/// The search-mode Tool selection policy of this Agent: one group over the bound Tool.
fn search_policy(&self) -> ToolSelectionPolicy {
ToolSelectionPolicy {
mode: ToolAccessMode::Search,
groups: vec![ToolGroup {
id: "crm".to_owned(),
name: "CRM".to_owned(),
description: "CRM operations".to_owned(),
tool_names: vec![self.operation.name.clone()],
}],
search: ToolSearchSettings::default(),
}
}
/// A commit that changes only the Tool selection policy: same Tool, Resource and Prompt
/// bindings, direct mode -> search mode. The served `tools/list` changes from the bound Tool to
/// `search_tools`/`call_tool`, so this is a visible Tool catalog change.
async fn commit_policy_only_change(&self) {
let version = self.next_draft_version().await;
self.open_draft(version).await;
self.configure_draft_with_policy(
version,
&self.tool_bindings(),
&self.search_policy(),
&[],
&self.base_prompts(),
)
.await;
self.publish_version(version).await;
}
/// A search-mode commit that only adds a Tool binding: `tools/list` still serves exactly
/// `search_tools`/`call_tool`, so it must not announce a Tools change.
async fn commit_search_mode_binding_change(&self) {
let version = self.next_draft_version().await;
self.open_draft(version).await;
self.configure_draft_with_policy(
version,
&self.both_tool_bindings(),
&self.search_policy(),
&[],
&self.base_prompts(),
)
.await;
self.publish_version(version).await;
}
/// Publish an independent Agent of the same workspace, bound to the first fixture operation, and
/// return its read-only MCP client key.
async fn publish_other_agent(&self, slug: &str) -> String {
let agent_id = test_agent_id(slug);
let now = OffsetDateTime::now_utc();
self.registry
.create_agent(CreateAgentRequest {
agent: &Agent {
id: agent_id.clone(),
workspace_id: test_workspace_id(),
slug: slug.to_owned(),
display_name: slug.to_owned(),
description: "Story 3.5 isolation fixture".to_owned(),
status: AgentStatus::Draft,
current_draft_version: 1,
latest_published_version: None,
created_at: now,
updated_at: now,
published_at: None,
},
version: &AgentVersion {
agent_id: agent_id.clone(),
version: 1,
status: AgentStatus::Draft,
instructions: json!({}),
tool_selection_policy: ToolSelectionPolicy::default(),
created_at: now,
},
bindings: &[binding_for_operation(&self.operation)],
})
.await
.expect("the second Agent is created");
self.registry
.publish_agent(PublishAgentRequest {
workspace_id: &test_workspace_id(),
agent_id: &agent_id,
version: 1,
published_at: &OffsetDateTime::now_utc(),
published_by: Some("alice"),
expected_state: None,
})
.await
.expect("the second Agent publishes");
create_platform_api_key(
&self.registry,
slug,
"mcp-signals-other",
&[PlatformApiKeyScope::Read],
)
.await
}
/// A committed Tool-only change of the independent Agent: it binds the second fixture Tool.
async fn commit_other_agent_tool_change(&self, slug: &str) {
let agent_id = test_agent_id(slug);
let version = AgentVersion {
agent_id: agent_id.clone(),
version: 2,
status: AgentStatus::Draft,
instructions: json!({}),
tool_selection_policy: ToolSelectionPolicy::default(),
created_at: OffsetDateTime::now_utc(),
};
self.registry
.create_agent_draft_version(CreateAgentDraftVersionRequest {
workspace_id: &test_workspace_id(),
agent_id: &agent_id,
version: &version,
bindings: &[],
updated_at: &OffsetDateTime::now_utc(),
})
.await
.expect("a second draft version of the other Agent opens");
self.registry
.save_agent_catalog_config_editable_with_prompts(
SaveAgentCatalogConfigRequest {
workspace_id: &test_workspace_id(),
agent_id: &agent_id,
agent_version: 2,
bindings: &self.both_tool_bindings(),
tool_selection_policy: &ToolSelectionPolicy::default(),
resource_bindings: &[],
expected_state: None,
},
&[],
)
.await
.expect("the other Agent's second catalog config saves");
self.registry
.publish_agent(PublishAgentRequest {
workspace_id: &test_workspace_id(),
agent_id: &agent_id,
version: 2,
published_at: &OffsetDateTime::now_utc(),
published_by: Some("alice"),
expected_state: None,
})
.await
.expect("the other Agent's second version publishes");
}
}
/// A live SSE response, read event by event.
@@ -714,6 +901,17 @@ fn resource_uris(list: &Value) -> Vec<String> {
.collect()
}
fn tool_names(list: &Value) -> Vec<String> {
let mut names: Vec<String> = list["result"]["tools"]
.as_array()
.unwrap_or_else(|| panic!("tools/list must return a page: {list}"))
.iter()
.map(|tool| tool["name"].as_str().unwrap().to_owned())
.collect();
names.sort();
names
}
/// Write a stand file that only the current user may read (credential files live here).
fn write_private(path: &PathBuf, contents: &str) {
use std::io::Write as _;
@@ -127,12 +127,20 @@ async fn legacy_stream_announces_a_committed_catalog_change_after_the_commit() {
"resources/list must serve the newly bound Resource: {resources}"
);
// A Tool-only commit keeps the Resource/Prompt projection: no further signal.
// A Tool-only commit keeps the Resource/Prompt projection: only a Tools frame follows (Story 3.5).
endpoint.commit_tool_only_change().await;
let frame = stream
.expect_frame("the committed Tools list-change signal")
.await;
assert_eq!(frame["method"], TOOL_LIST_CHANGED);
assert!(
frame.get("params").is_none(),
"a legacy list-change notification carries no parameters: {frame}"
);
stream
.expect_silence(
Duration::from_millis(2_500),
"signal for a Tool-only commit",
"a Resource or Prompt signal for a Tool-only commit",
)
.await;
}
@@ -162,7 +170,11 @@ async fn modern_listen_stream_acknowledges_then_announces_coalesced_changes() {
);
assert_eq!(
acknowledgement["params"]["notifications"],
json!({ "promptsListChanged": true, "resourcesListChanged": true }),
json!({
"promptsListChanged": true,
"resourcesListChanged": true,
"toolsListChanged": true
}),
"only the implemented list-change types are acknowledged: {acknowledgement}"
);
@@ -173,7 +185,7 @@ async fn modern_listen_stream_acknowledges_then_announces_coalesced_changes() {
endpoint.commit_tool_only_change().await;
let mut methods = Vec::new();
for _ in 0..2 {
for _ in 0..3 {
let frame = stream
.expect_frame("the coalesced list-change signal")
.await;
@@ -185,7 +197,8 @@ async fn modern_listen_stream_acknowledges_then_announces_coalesced_changes() {
methods,
vec![
PROMPT_LIST_CHANGED.to_owned(),
RESOURCE_LIST_CHANGED.to_owned()
RESOURCE_LIST_CHANGED.to_owned(),
TOOL_LIST_CHANGED.to_owned()
]
);
stream
@@ -228,8 +241,8 @@ async fn modern_listen_delivers_only_the_negotiated_signal_types() {
);
assert_eq!(
acknowledgement["params"]["notifications"],
json!({ "promptsListChanged": true }),
"only the implemented and requested type is acknowledged: {acknowledgement}"
json!({ "promptsListChanged": true, "toolsListChanged": true }),
"only the implemented and requested types are acknowledged: {acknowledgement}"
);
// The watcher takes its baseline before it can report anything.
@@ -256,7 +269,7 @@ async fn modern_listen_delivers_only_the_negotiated_signal_types() {
json!("prompts-only")
);
// Neither `toolsListChanged` nor `resourceSubscriptions` were honoured, so nothing else follows.
// No Tool commit happened, so no Tools frame follows; `resourceSubscriptions` was not honoured.
stream
.expect_silence(
Duration::from_millis(2_500),
@@ -354,6 +367,11 @@ async fn a_lost_notification_is_recovered_through_the_authoritative_methods() {
discover["result"]["capabilities"]["resources"]["listChanged"],
json!(true)
);
assert_eq!(
discover["result"]["capabilities"]["tools"]["listChanged"],
json!(true),
"the Tools list-change capability is advertised: {discover}"
);
let resources = endpoint.modern("resources/list", json!({})).await;
assert!(
resource_uris(&resources)
@@ -414,3 +432,360 @@ async fn a_lost_notification_is_recovered_through_the_authoritative_methods() {
"re-initialization serves the authoritative catalog: {prompts}"
);
}
// ------------------------------------------------------------------------------------------------
// Story 3.5 (FR-14): Tool catalog change signals. A client that negotiated the Tools list-changed
// notification learns about a *committed* Tool catalog change, and `tools/list` stays the
// authoritative source for a client without the notification or after a reconnect.
// ------------------------------------------------------------------------------------------------
/// AT-3.5-01/02 (modern): the Tools signal is delivered only to the stream that negotiated it, once
/// per committed change, and `tools/list` serves the same committed snapshot.
#[tokio::test]
async fn modern_tools_list_changed_is_delivered_only_to_a_client_that_asks_for_it() {
let endpoint = signals_endpoint().await;
let mut tools = endpoint
.listen(json!(51), json!({ "toolsListChanged": true }))
.await;
let mut prompts = endpoint
.listen(json!(52), json!({ "promptsListChanged": true }))
.await;
let acknowledgement = tools.expect_frame("the Tools acknowledgment").await;
assert_eq!(acknowledgement["method"], SUBSCRIPTIONS_ACKNOWLEDGED);
assert_eq!(
acknowledgement["params"]["notifications"],
json!({ "toolsListChanged": true }),
"the Tools list-change type must be honoured and acknowledged: {acknowledgement}"
);
let other = prompts.expect_frame("the Prompts acknowledgment").await;
assert_eq!(
other["params"]["notifications"],
json!({ "promptsListChanged": true }),
"a stream that did not ask for Tools is acknowledged without it: {other}"
);
// The watchers take their baseline before they can report anything.
tokio::time::sleep(Duration::from_millis(1_500)).await;
// A draft-only edit is not a commit: nothing is announced.
endpoint.edit_draft_without_publishing().await;
tools
.expect_silence(
Duration::from_millis(2_500),
"Tools signal for a draft-only edit",
)
.await;
// A committed Resource/Prompt change is not a Tools change: the Tools stream stays silent while
// the Prompts stream receives exactly its own type.
endpoint.commit_resource_and_prompt_change().await;
let prompt_frame = prompts
.expect_frame("the committed Prompt list-change signal")
.await;
assert_eq!(prompt_frame["method"], PROMPT_LIST_CHANGED);
tools
.expect_silence(
Duration::from_millis(2_500),
"Tools signal for a Resource/Prompt commit",
)
.await;
// One committed Tool catalog change is announced exactly once.
endpoint.commit_tool_only_change().await;
let frame = tools
.expect_frame("the committed Tools list-change signal")
.await;
assert_eq!(frame["jsonrpc"], json!("2.0"));
assert_eq!(frame["method"], TOOL_LIST_CHANGED);
assert_eq!(frame["params"]["_meta"][SUBSCRIPTION_ID_KEY], json!(51));
tools
.expect_silence(Duration::from_millis(2_500), "a repeated Tools signal")
.await;
// The prompts-only stream was never told about Tools, even though the commit happened after it
// opened.
prompts
.expect_silence(Duration::from_millis(1_200), "unrequested Tools signal")
.await;
// `tools/list` is authoritative for the same committed state, notification or not.
let list = endpoint.modern("tools/list", json!({})).await;
assert_eq!(
tool_names(&list),
vec!["crm_create_lead".to_owned(), "crm_create_second".to_owned()]
);
}
/// AT-3.5-01/02 (legacy): the legacy `GET` stream carries the Tools signal after the commit; a
/// Resource/Prompt commit produces no Tools frame; a committed change of another Agent is never
/// disclosed on this stream, and `tools/list` stays authoritative.
#[tokio::test]
async fn legacy_stream_announces_a_committed_tools_change_and_never_another_agents() {
let endpoint = signals_endpoint().await;
let other_key = endpoint.publish_other_agent(OTHER_AGENT_SLUG).await;
let session = endpoint.legacy_session().await;
let mut stream = endpoint.legacy_stream(&session).await;
tokio::time::sleep(Duration::from_millis(1_500)).await;
stream
.expect_silence(Duration::from_millis(1_200), "signal before any commit")
.await;
// A committed Resource/Prompt change keeps the Tool binding set: no Tools frame.
endpoint.commit_resource_and_prompt_change().await;
let mut methods = Vec::new();
for _ in 0..2 {
let frame = stream.expect_frame("the committed catalog signals").await;
assert!(
frame.get("params").is_none(),
"a legacy list-change notification carries no parameters: {frame}"
);
methods.push(frame["method"].as_str().unwrap().to_owned());
}
methods.sort();
assert_eq!(
methods,
vec![
PROMPT_LIST_CHANGED.to_owned(),
RESOURCE_LIST_CHANGED.to_owned()
],
"a Resource/Prompt commit must not announce Tools"
);
// A committed Tool change of another Agent of the same workspace never reaches this stream or
// this Agent's `tools/list`.
endpoint
.commit_other_agent_tool_change(OTHER_AGENT_SLUG)
.await;
stream
.expect_silence(
Duration::from_millis(2_500),
"Tools signal for another Agent's commit",
)
.await;
let isolated = endpoint.legacy(&session, "tools/list", json!({})).await;
assert_eq!(
tool_names(&isolated),
vec!["crm_create_lead".to_owned()],
"another Agent's commit must not change this Agent's catalog: {isolated}"
);
// The commit really happened: the other Agent serves its own two-Tool catalog.
let other_url = agent_mcp_url(&endpoint.base_url, OTHER_AGENT_SLUG);
let other_session = initialize_session(&endpoint.client, &other_url, &other_key).await;
let other_list = endpoint
.client
.post(&other_url)
.header(header::ACCEPT, "application/json, text/event-stream")
.header(header::AUTHORIZATION, format!("Bearer {other_key}"))
.header("MCP-Protocol-Version", LEGACY_REVISION)
.header("MCP-Session-Id", &other_session)
.json(&json!({
"jsonrpc": "2.0",
"id": 7,
"method": "tools/list",
"params": {}
}))
.send()
.await
.unwrap();
let other_list: Value = serde_json::from_str(&other_list.text().await.unwrap()).unwrap();
assert_eq!(
tool_names(&other_list),
vec!["crm_create_lead".to_owned(), "crm_create_second".to_owned()],
"the other Agent's committed catalog changed: {other_list}"
);
// This Agent's committed Tool change is announced after the commit, exactly once.
endpoint.commit_tool_only_change().await;
let frame = stream
.expect_frame("the committed Tools list-change signal")
.await;
assert_eq!(frame["method"], TOOL_LIST_CHANGED);
assert!(
frame.get("params").is_none(),
"a legacy list-change notification carries no parameters: {frame}"
);
stream
.expect_silence(
Duration::from_millis(2_500),
"a repeated or unrequested signal",
)
.await;
let list = endpoint.legacy(&session, "tools/list", json!({})).await;
assert_eq!(
tool_names(&list),
vec!["crm_create_lead".to_owned(), "crm_create_second".to_owned()],
"tools/list must serve the committed catalog without the notification: {list}"
);
}
/// AT-3.5-04: the Tools signal follows the same projection `tools/list` serves, so a committed
/// publication that only changes the Tool selection policy is announced on both revisions, while a
/// committed binding change that leaves `tools/list` unchanged is silent.
#[tokio::test]
async fn a_policy_only_commit_is_announced_on_both_revisions_and_an_invisible_change_is_silent() {
let endpoint = signals_endpoint().await;
let direct_projection = vec!["crm_create_lead".to_owned()];
// `tool_names` sorts the served page.
let search_projection = vec!["call_tool".to_owned(), "search_tools".to_owned()];
// Both revisions negotiate the Tools signal and take their baseline before anything can arrive.
let mut modern = endpoint
.listen(json!(61), json!({ "toolsListChanged": true }))
.await;
let acknowledgement = modern.expect_frame("the Tools acknowledgment").await;
assert_eq!(acknowledgement["method"], SUBSCRIPTIONS_ACKNOWLEDGED);
assert_eq!(
acknowledgement["params"]["notifications"],
json!({ "toolsListChanged": true })
);
let session = endpoint.legacy_session().await;
let mut legacy = endpoint.legacy_stream(&session).await;
tokio::time::sleep(Duration::from_millis(1_500)).await;
// The served projection before the commit is the direct-mode binding itself.
assert_eq!(
tool_names(&endpoint.modern("tools/list", json!({})).await),
direct_projection
);
// A policy-only commit: identical Tool/Resource/Prompt bindings, direct -> search mode. The
// served list changes, so each negotiated stream receives exactly one Tools frame.
endpoint.commit_policy_only_change().await;
let modern_frame = modern
.expect_frame("the committed Tools list-change signal (modern)")
.await;
assert_eq!(modern_frame["method"], TOOL_LIST_CHANGED);
assert_eq!(
modern_frame["params"]["_meta"][SUBSCRIPTION_ID_KEY],
json!(61)
);
let legacy_frame = legacy
.expect_frame("the committed Tools list-change signal (legacy)")
.await;
assert_eq!(legacy_frame["method"], TOOL_LIST_CHANGED);
assert!(
legacy_frame.get("params").is_none(),
"a legacy list-change notification carries no parameters: {legacy_frame}"
);
modern
.expect_silence(
Duration::from_millis(2_500),
"a repeated modern Tools signal",
)
.await;
legacy
.expect_silence(
Duration::from_millis(2_500),
"a repeated legacy Tools signal",
)
.await;
// `tools/list` is authoritative for the new projection on both revisions.
assert_eq!(
tool_names(&endpoint.modern("tools/list", json!({})).await),
search_projection
);
assert_eq!(
tool_names(&endpoint.legacy(&session, "tools/list", json!({})).await),
search_projection
);
// The inverse direction: in search mode a binding-only commit does not change `tools/list`, so
// neither stream may claim a visible Tool change.
endpoint.commit_search_mode_binding_change().await;
modern
.expect_silence(
Duration::from_millis(3_500),
"a Tools signal for an unchanged modern tools/list",
)
.await;
legacy
.expect_silence(
Duration::from_millis(2_500),
"a Tools signal for an unchanged legacy tools/list",
)
.await;
assert_eq!(
tool_names(&endpoint.modern("tools/list", json!({})).await),
search_projection
);
}
/// AT-3.5-02/03: a client that missed the notification recovers Tool discovery from the authoritative
/// state — the modern stateless client after a reconnect, and the legacy client after re-initializing
/// a retired session — and a reconnected stream never replays the missed change.
#[tokio::test]
async fn a_reconnected_client_recovers_tools_discovery_from_the_authoritative_state() {
let endpoint = signals_endpoint().await;
// Modern: the commit happens while no stream is open at all, then a client reconnects.
endpoint.commit_tool_only_change().await;
let mut reconnected = endpoint
.listen(
json!("after-reconnect"),
json!({ "toolsListChanged": true }),
)
.await;
let acknowledgement = reconnected.expect_frame("the Tools acknowledgment").await;
assert_eq!(
acknowledgement["params"]["notifications"],
json!({ "toolsListChanged": true })
);
// The baseline of a new stream is the committed state: the missed change is not replayed.
reconnected
.expect_silence(
Duration::from_millis(2_500),
"a replayed Tools signal after reconnect",
)
.await;
let list = endpoint.modern("tools/list", json!({})).await;
assert_eq!(
tool_names(&list),
vec!["crm_create_lead".to_owned(), "crm_create_second".to_owned()],
"a client without the notification recovers the committed catalog: {list}"
);
// Legacy: one more committed Tool change is announced on the live stream, then the session is
// retired and the client re-initializes.
let session = endpoint.legacy_session().await;
let mut stale = endpoint.legacy_stream(&session).await;
tokio::time::sleep(Duration::from_millis(1_500)).await;
endpoint.commit_tool_only_revert().await;
let frame = stale
.expect_frame("the committed Tools list-change signal")
.await;
assert_eq!(frame["method"], TOOL_LIST_CHANGED);
let deleted = endpoint
.client
.delete(&endpoint.mcp_url)
.header(
header::AUTHORIZATION,
format!("Bearer {}", endpoint.api_key),
)
.header("MCP-Protocol-Version", LEGACY_REVISION)
.header("MCP-Session-Id", &session)
.send()
.await
.unwrap();
assert_eq!(deleted.status(), reqwest::StatusCode::NO_CONTENT);
let fresh = endpoint.legacy_session().await;
let list = endpoint.legacy(&fresh, "tools/list", json!({})).await;
assert_eq!(
tool_names(&list),
vec!["crm_create_lead".to_owned()],
"re-initialization serves the committed catalog: {list}"
);
// A stream reopened after the reconnect starts from the committed baseline, not from a replay.
let mut reopened = endpoint.legacy_stream(&fresh).await;
reopened
.expect_silence(
Duration::from_millis(2_500),
"a replayed Tools signal on a reconnected stream",
)
.await;
}
@@ -0,0 +1,868 @@
//! 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. It must exceed [`LONG_HOLD_MS`]: a call that was *not*
/// stopped completes its upstream request and records the outcome inside this window, so the checks
/// after it prove that the cancellation stopped the call rather than only that it had not finished
/// yet.
const CANCEL_GRACE_MS: u64 = 2_500;
/// The suite depends on that order: the constant must not silently drop back below the hold.
const _: () = assert!(CANCEL_GRACE_MS > LONG_HOLD_MS);
#[derive(Clone, Copy, Debug)]
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(&registry, &operation, agent_slug).await;
let scopes = [PlatformApiKeyScope::Read, PlatformApiKeyScope::Write];
let api_key = create_platform_api_key(&registry, agent_slug, "mcp-lifecycle", &scopes).await;
let other_api_key =
create_platform_api_key(&registry, 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" })
);
}
// ---------------------------------------------------------------------------------------------
// AT-3.4-01 (TL correction): the official SDK sends the dual `Accept` JSON-first. A `tools/call`
// that carries a validated token and offers `text/event-stream` in that same header must still be
// answered on its own stream, wherever the media types are ordered.
// ---------------------------------------------------------------------------------------------
#[tokio::test]
async fn at_3_4_01_json_first_dual_accept_keeps_progress_for_a_valid_token() {
/// Exactly what the official MCP SDK sends when it can read a stream.
const SDK_ACCEPT: &str = "application/json, text/event-stream";
let fixture = fixture("lifecycle-json-first", HOLD_MS, 5_000).await;
let session = initialize_session(&fixture.client, &fixture.mcp_url, &fixture.api_key).await;
for revision in [Revision::Legacy, Revision::Modern] {
let carrier = match revision {
Revision::Legacy => Some(session.as_str()),
Revision::Modern => None,
};
let token = json!("tok-json-first");
let reply = fixture
.send(
SDK_ACCEPT,
&fixture.api_key,
revision,
550,
fixture.call_params(Some(token.clone()), revision),
carrier,
Some("req-json-first"),
)
.await;
reply.assert_stream();
let progress = reply.progress_frames();
assert!(
!progress.is_empty(),
"{revision:?}: a valid token with an acceptable stream must produce progress, got {}",
reply.raw
);
for frame in &progress {
assert_eq!(frame["params"]["progressToken"], token, "{frame}");
assert!(
frame["params"].get("total").is_none(),
"this server knows no total: {frame}"
);
}
let values = progress_values(&progress);
assert!(
values.windows(2).all(|pair| pair[0] < pair[1]),
"{revision:?}: progress must be strictly monotonic, got {values:?}"
);
assert_eq!(values, vec![1, 2, 3], "{revision:?}: got {values:?}");
let terminal = reply.terminal();
assert_eq!(terminal["id"], json!(550), "{revision:?}");
assert_eq!(terminal["result"]["isError"], json!(false), "{revision:?}");
assert_eq!(
terminal["result"]["structuredContent"],
json!({ "id": "lead_123" }),
"{revision:?}"
);
}
// The correction is scoped to a call that can actually carry progress: the same JSON-first
// header without a token, and with an unusable token, keeps the negotiated single JSON body.
for token in [None, Some(json!("x".repeat(4096)))] {
let reply = fixture
.send(
SDK_ACCEPT,
&fixture.api_key,
Revision::Legacy,
551,
fixture.call_params(token.clone(), Revision::Legacy),
Some(&session),
None,
)
.await;
assert_eq!(reply.status, reqwest::StatusCode::OK);
assert!(
reply.content_type.starts_with("application/json"),
"token {token:?} must keep the negotiated JSON body, got {:?}: {}",
reply.content_type,
reply.raw
);
assert!(reply.progress_frames().is_empty(), "{token:?}");
assert_eq!(
reply.terminal()["result"]["structuredContent"],
json!({ "id": "lead_123" }),
"token {token:?}"
);
}
}
#[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;
// Both supported revisions read the token from the same pinned `RequestMetaObject` field, so an
// unusable token must behave identically in each of them: no progress, unchanged result.
for revision in [Revision::Legacy, Revision::Modern] {
let carrier = match revision {
Revision::Legacy => Some(session.as_str()),
Revision::Modern => None,
};
let tokens = [
json!(""),
json!({ "not": "a token" }),
json!([1, 2]),
json!(true),
json!("x".repeat(4096)),
];
let mut observed = Vec::new();
for token in tokens {
let reply = fixture
.call_stream(
revision,
520,
fixture.call_params(Some(token.clone()), revision),
carrier,
"req-bad-token",
)
.await;
observed.push((token, reply));
}
for (token, reply) in observed {
assert!(
reply.progress_frames().is_empty(),
"{revision:?}: token {token} must not produce progress, got {}",
reply.raw
);
let terminal = reply.terminal();
assert_eq!(
terminal["result"]["structuredContent"],
json!({ "id": "lead_123" }),
"{revision:?}: 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" })
);
}
+6
View File
@@ -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));
+25 -19
View File
@@ -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,
+18 -5
View File
@@ -17,8 +17,8 @@ use crate::{
rate_limit::{rate_limited_jsonrpc_response, rate_limited_status_response},
request_context::RequestContext,
transport::{
accepts_event_stream, negotiate_post_response_mode, session_id_from_headers, sse_response,
transport_response, validate_get_accept_header, validate_origin,
ResponseMode, accepts_event_stream, negotiate_post_response_mode, session_id_from_headers,
sse_response, transport_response, validate_get_accept_header, validate_origin,
validate_session_protocol_version, with_request_id_header,
},
};
@@ -103,7 +103,7 @@ pub(super) async fn mcp_get(
};
// Story 3.19: the pinned legacy transport forbids broadcasting one JSON-RPC message across the
// SSE streams of a session, so exactly one admitted `GET` receives the Resource/Prompt
// SSE streams of a session, so exactly one admitted `GET` receives the Resource/Prompt/Tool
// list-change signals. A newer `GET` takes them over and the older stream simply ends; a
// `DELETE` retires the producer, so a stale generation never writes into a reconnect.
let Some(generation) = state.signal_streams.admit(&session_id) else {
@@ -115,7 +115,7 @@ pub(super) async fn mcp_get(
crate::protocol::Watch {
workspace_slug: path.workspace_slug.clone(),
agent_slug: path.agent_slug.clone(),
signals: crate::protocol::Signals::BOTH,
signals: crate::protocol::Signals::ALL,
wire: crate::protocol::Wire::Legacy,
legacy_stream: Some((
Arc::clone(&state.signal_streams),
@@ -256,7 +256,7 @@ async fn mcp_post_response(
return status.into_response();
}
let response_mode = match negotiate_post_response_mode(headers) {
let mut response_mode = match negotiate_post_response_mode(headers) {
Ok(mode) => mode,
Err(status) => return status.into_response(),
};
@@ -365,6 +365,19 @@ async fn mcp_post_response(
Err(error) => return error.into_response(),
};
// Story 3.4 correction: the official SDK lists the media types JSON-first. For a `tools/call`
// that carries a validated progress token and offered `text/event-stream`, the stream is the only
// carrier that can deliver the progress the client asked for, so the media-type order is not a
// preference for the JSON body here. Every other request — another method, no token, an unusable
// token, a JSON-only `Accept` — keeps the negotiated mode, and no admission check moved.
if matches!(response_mode, ResponseMode::Json)
&& method_name(message) == Some("tools/call")
&& accepts_event_stream(headers)
&& crate::app::lifecycle::token_from_meta(message.pointer("/params/_meta")).is_some()
{
response_mode = ResponseMode::Sse;
}
if matches!(identity.era, RequestEra::Modern) {
// ERA_MODERN_ENTER (spec section 7.2): this request entered the modern era-adapter.
#[cfg(test)]
@@ -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,566 @@
//! 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 — and nothing else claims the
/// opposite either: the call is stopped before its terminal outcome, so its Invocation History holds
/// no row for this call at all (see the module docs for why there is no invented cancellation code).
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
+92 -66
View File
@@ -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)]
@@ -369,7 +373,9 @@ pub(crate) const CAPABILITY_DESCRIPTORS: &[CapabilityIdDescriptor] = &[
extension: None,
deprecated: None,
sub_features: FeatureSet(&["listChanged"]),
advertised: Some(("tools", &[("listChanged", false)])),
// Story 3.5: the adapter emits `notifications/tools/list_changed` from the committed
// published Tool bindings of the Agent snapshot, so the declaration is now true.
advertised: Some(("tools", &[("listChanged", true)])),
revisions: MODERN_AND_LEGACY,
},
CapabilityIdDescriptor {
@@ -599,6 +605,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)]
@@ -39,7 +39,7 @@ fn static_registration_is_unique_and_advertises_only_the_registered_capability()
"logging": {},
"prompts": {"listChanged": true},
"resources": {"listChanged": true, "subscribe": false},
"tools": {"listChanged": false}
"tools": {"listChanged": true}
}),
"the registered advertisement must be the same reviewed object in {revision}"
);
@@ -50,7 +50,7 @@ fn static_registration_is_unique_and_advertises_only_the_registered_capability()
"logging": {},
"prompts": {"listChanged": true},
"resources": {"listChanged": true, "subscribe": false},
"tools": {"listChanged": false}
"tools": {"listChanged": true}
}),
"the production advertisement entry point must serve {revision}"
);
@@ -264,7 +264,7 @@ fn an_inert_test_descriptor_changes_both_projections_and_is_never_registered_in_
"logging": {},
"prompts": {"listChanged": true},
"resources": {"listChanged": true, "subscribe": false},
"tools": {"listChanged": false}
"tools": {"listChanged": true}
})
);
assert_eq!(
@@ -275,7 +275,7 @@ fn an_inert_test_descriptor_changes_both_projections_and_is_never_registered_in_
"logging": {},
"prompts": {"listChanged": true},
"resources": {"listChanged": true, "subscribe": false},
"tools": {"listChanged": false}
"tools": {"listChanged": true}
})
);
assert_eq!(
@@ -286,7 +286,7 @@ fn an_inert_test_descriptor_changes_both_projections_and_is_never_registered_in_
"logging": {},
"prompts": {"listChanged": true},
"resources": {"listChanged": true, "subscribe": false},
"tools": {"listChanged": false}
"tools": {"listChanged": true}
})
);
@@ -470,7 +470,7 @@ fn a_single_era_descriptor_never_leaks_into_the_other_era_advertisement() {
"logging": {},
"prompts": {"listChanged": true},
"resources": {"listChanged": true, "subscribe": false},
"tools": {"listChanged": false}
"tools": {"listChanged": true}
}),
"the other era advertisement stays the reviewed object"
);
@@ -761,7 +761,7 @@ fn adding_and_removing_a_method_descriptor_changes_the_dispatch_decision() {
"logging": {},
"prompts": {"listChanged": true},
"resources": {"listChanged": true, "subscribe": false},
"tools": {"listChanged": false}
"tools": {"listChanged": true}
})
);
}
@@ -1,13 +1,15 @@
//! Story 3.19: Resource and Prompt list-change signals (FR-19).
//! Story 3.19: Resource and Prompt list-change signals (FR-19); Story 3.5 adds the Tools signal of
//! the same seam (FR-14).
//!
//! The positive result of the story is that a client which asked for the list-change signal of its
//! revision learns that the *committed* Resource or Prompt catalog changed, and that the ordinary
//! `resources/list`, `resources/read`, `resources/templates/list`, `prompts/list` and `prompts/get`
//! stay authoritative for a client that misses the notification.
//! revision learns that the *committed* Resource, Prompt or Tool catalog changed, and that the
//! ordinary `resources/list`, `resources/read`, `resources/templates/list`, `prompts/list`,
//! `prompts/get` and `tools/list` stay authoritative for a client that misses the notification.
//!
//! Shape of the chosen seam (ARC decision, kanban t_c12863fb): a **stream-local watcher**. One open
//! notification stream owns one bounded periodic read of the published Agent catalog the stream is
//! scoped to; a change of the visible Resource/Prompt binding projection produces the revision's
//! scoped to; a change of the visible Resource/Prompt/Tool projection of that snapshot (the Resource
//! and Prompt bindings plus the exact Tool definitions `tools/list` serves) produces the revision's
//! list-change notification. There is no post-commit hook, no cross-process bus and no durable
//! queue: the committed catalog is the source of truth, so a signal can never be produced before its
//! commit, and a failed read can never roll the commit back — it only skips that tick and stays
@@ -55,6 +57,8 @@ pub(crate) const SUBSCRIPTION_ID_KEY: &str = "io.modelcontextprotocol/subscripti
pub(crate) const RESOURCE_LIST_CHANGED: &str = "notifications/resources/list_changed";
/// `notifications/prompts/list_changed` (both approved revisions).
pub(crate) const PROMPT_LIST_CHANGED: &str = "notifications/prompts/list_changed";
/// `notifications/tools/list_changed` (both approved revisions, Story 3.5).
pub(crate) const TOOL_LIST_CHANGED: &str = "notifications/tools/list_changed";
/// `notifications/subscriptions/acknowledged` (modern revision only).
pub(crate) const SUBSCRIPTIONS_ACKNOWLEDGED: &str = "notifications/subscriptions/acknowledged";
@@ -79,29 +83,32 @@ pub(crate) const MAX_FILTER_URI_BYTES: usize = 2_048;
/// The one safe detail of a malformed or oversized `subscriptions/listen` filter.
pub(crate) const INVALID_LISTEN_FILTER: &str = "invalid subscriptions/listen notification filter";
/// The two list-change signal types this server implements.
/// The three list-change signal types this server implements.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub(crate) struct Signals {
pub(crate) resources: bool,
pub(crate) prompts: bool,
pub(crate) tools: bool,
}
impl Signals {
/// Both types: the legacy revision defines no client opt-in, so its stream carries both.
pub(crate) const BOTH: Self = Self {
/// All types: the legacy revision defines no client opt-in, so its stream carries every type.
pub(crate) const ALL: Self = Self {
resources: true,
prompts: true,
tools: true,
};
#[cfg_attr(not(test), allow(dead_code))] // read by the unit oracle of the projection
pub(crate) fn any(self) -> bool {
self.resources || self.prompts
self.resources || self.prompts || self.tools
}
fn intersect(self, other: Self) -> Self {
Self {
resources: self.resources && other.resources,
prompts: self.prompts && other.prompts,
tools: self.tools && other.tools,
}
}
}
@@ -114,8 +121,6 @@ impl Signals {
#[serde(rename_all = "camelCase")]
pub(crate) struct ListenFilter {
#[serde(default)]
/// `toolsListChanged` is not implemented in this scope and is therefore never acknowledged.
#[allow(dead_code)]
tools_list_changed: bool,
#[serde(default)]
prompts_list_changed: bool,
@@ -145,9 +150,9 @@ pub(crate) enum FilterOutcome {
impl ListenFilter {
/// Validate the bounded inputs and keep only the honoured types.
///
/// `toolsListChanged` and `resourceSubscriptions` are not implemented in the current scope, which
/// is what the acknowledgment reports: they are simply not honoured, and the pinned schema
/// forbids the server from sending a type it did not agree to.
/// `resourceSubscriptions` is not implemented in the current scope, which is what the
/// acknowledgment reports: it is simply not honoured, and the pinned schema forbids the server
/// from sending a type it did not agree to.
pub(crate) fn accepted(&self) -> FilterOutcome {
if self.resource_subscriptions.len() > MAX_FILTER_URIS
|| self
@@ -160,6 +165,7 @@ impl ListenFilter {
FilterOutcome::Accepted(Signals {
resources: self.resources_list_changed,
prompts: self.prompts_list_changed,
tools: self.tools_list_changed,
})
}
}
@@ -173,16 +179,23 @@ fn acknowledged_filter_wire(accepted: Signals) -> Value {
if accepted.resources {
filter.insert("resourcesListChanged".to_owned(), Value::Bool(true));
}
if accepted.tools {
filter.insert("toolsListChanged".to_owned(), Value::Bool(true));
}
Value::Object(filter)
}
/// The exact bound Resource/Prompt projection of one published Agent catalog.
/// The exact bound Resource/Prompt/Tool projection of one published Agent catalog.
///
/// The projection is derived from the same committed catalog read that already feeds
/// `resources/list`, `resources/templates/list`, `prompts/list` and `prompts/get`: the exact Resource
/// and Prompt bindings of the published Agent snapshot, in deterministic binding order.
/// `catalog_revision` alone is *not* the comparison key — a commit that only changes Tools must not
/// produce a Resource/Prompt signal — so the two binding vectors are compared on their own.
/// `resources/list`, `resources/templates/list`, `prompts/list`, `prompts/get` and `tools/list`: the
/// exact Resource and Prompt bindings of the published Agent snapshot, in deterministic binding
/// order, and the exact Tool definitions that `tools/list` would serve. The Tool part is taken from
/// [`crate::manifest::catalog_tool_definitions`] rather than from the bindings, because that is the
/// projection the client sees: it also depends on the Tool selection policy (mode, groups, search
/// settings), and in `Search` mode it does not depend on the bindings at all. `catalog_revision`
/// alone is *not* the comparison key — a commit that only changes Tools must not produce a Resource
/// or Prompt signal, and vice versa — so the three projections are compared on their own.
///
/// shortcut: a Resource revocation invalidates a bound publication without a new Agent snapshot, so
/// it does not change this projection and produces no list-change signal; the revocation gate at
@@ -192,40 +205,45 @@ fn acknowledged_filter_wire(accepted: Signals) -> Value {
pub(crate) struct CatalogFingerprint {
resources: Vec<(String, u32)>,
prompts: Vec<(String, u32)>,
/// Canonical JSON of every definition `tools/list` serves, sorted so a re-ordered read is not a
/// false change.
tools: Vec<String>,
}
impl CatalogFingerprint {
pub(crate) fn of(catalog: &PublishedAgentCatalog) -> Self {
let mut resources = catalog
.resources
.iter()
.map(|binding| {
fn sorted<T: Ord>(values: impl Iterator<Item = T>) -> Vec<T> {
let mut sorted = values.collect::<Vec<_>>();
sorted.sort_unstable();
sorted
}
Self {
resources: sorted(catalog.resources.iter().map(|binding| {
(
binding.resource_id.as_str().to_owned(),
binding.resource_version,
)
})
.collect::<Vec<_>>();
let mut prompts = catalog
.prompts
.iter()
.map(|binding| {
})),
prompts: sorted(catalog.prompts.iter().map(|binding| {
(
binding.prompt_id.as_str().to_owned(),
binding.prompt_version,
)
})
.collect::<Vec<_>>();
resources.sort();
prompts.sort();
Self { resources, prompts }
})),
tools: sorted(
crate::manifest::catalog_tool_definitions(catalog)
.into_iter()
.map(|definition| definition.to_string()),
),
}
}
/// The list-change types whose visible binding projection differs between `previous` and `self`.
/// The list-change types whose visible projection differs between `previous` and `self`.
pub(crate) fn changes_since(&self, previous: &Self) -> Signals {
Signals {
resources: self.resources != previous.resources,
prompts: self.prompts != previous.prompts,
tools: self.tools != previous.tools,
}
}
}
@@ -241,10 +259,11 @@ pub(crate) enum Wire {
impl Wire {
fn signal_frames(&self, signals: Signals) -> Vec<String> {
let mut frames = Vec::with_capacity(2);
let mut frames = Vec::with_capacity(3);
for (changed, method) in [
(signals.resources, RESOURCE_LIST_CHANGED),
(signals.prompts, PROMPT_LIST_CHANGED),
(signals.tools, TOOL_LIST_CHANGED),
] {
if !changed {
continue;
@@ -2,35 +2,59 @@
//! wire frames of both approved revisions and the bounded legacy stream ownership.
use std::{
collections::BTreeMap,
io,
sync::{Arc, Mutex},
time::{Duration, Instant},
};
use crank_core::ToolSelectionPolicy;
use crank_core::ids::{PromptId, ResourceId};
use crank_core::{
ExecutionConfig, HttpMethod, Operation, OperationId, OperationSecurityLevel, OperationStatus,
Protocol, RestTarget, Target, ToolAccessMode, ToolDescription, ToolGroup, ToolSearchSettings,
ToolSelectionPolicy, WorkspaceId,
};
use crank_mapping::MappingSet;
use crank_registry::PublishedAgentCatalog;
use crank_registry::model::{AgentPromptBinding, AgentResourceBinding};
use crank_registry::model::{AgentPromptBinding, AgentResourceBinding, PublishedAgentTool};
use crank_schema::{Schema, SchemaKind};
use serde_json::{Value, json};
use time::OffsetDateTime;
use tokio::sync::mpsc;
use super::{
CatalogFingerprint, FilterOutcome, INVALID_LISTEN_FILTER, ListenFilter, MAX_FILTER_URIS,
MAX_SUBSCRIPTION_ID_BYTES, PROMPT_LIST_CHANGED, RESOURCE_LIST_CHANGED, ReadError, Reader,
SIGNAL_QUEUE_CAPACITY, SUBSCRIPTION_ID_KEY, SUBSCRIPTIONS_ACKNOWLEDGED, Signals,
StreamRegistry, Watch, Wire, acknowledged_frame, run, subscription_id,
StreamRegistry, TOOL_LIST_CHANGED, Watch, Wire, acknowledged_frame, run, subscription_id,
};
fn catalog(
resources: &[(&str, u32)],
prompts: &[(&str, u32)],
catalog_revision: &str,
) -> PublishedAgentCatalog {
catalog_with(
ToolSelectionPolicy::default(),
Vec::new(),
resources,
prompts,
catalog_revision,
)
}
fn catalog_with(
tool_selection_policy: ToolSelectionPolicy,
tools: Vec<PublishedAgentTool>,
resources: &[(&str, u32)],
prompts: &[(&str, u32)],
catalog_revision: &str,
) -> PublishedAgentCatalog {
PublishedAgentCatalog {
agent_version: 1,
catalog_revision: catalog_revision.to_owned(),
tool_selection_policy: ToolSelectionPolicy::default(),
tools: Vec::new(),
tool_selection_policy,
tools,
resources: resources
.iter()
.map(|(id, version)| AgentResourceBinding {
@@ -48,6 +72,93 @@ fn catalog(
}
}
fn search_policy(tool_names: &[&str]) -> ToolSelectionPolicy {
ToolSelectionPolicy {
mode: ToolAccessMode::Search,
groups: vec![ToolGroup {
id: "crm".to_owned(),
name: "CRM".to_owned(),
description: "CRM operations".to_owned(),
tool_names: tool_names.iter().map(|name| (*name).to_owned()).collect(),
}],
search: ToolSearchSettings::default(),
}
}
fn empty_object_schema() -> Schema {
Schema {
kind: SchemaKind::Object,
format: None,
description: None,
required: false,
nullable: false,
default_value: None,
fields: BTreeMap::new(),
items: None,
enum_values: Vec::new(),
variants: Vec::new(),
}
}
/// One published Tool binding whose served definition is exactly `title`/`description`.
fn published_tool(name: &str, title: &str, description: &str, version: u32) -> PublishedAgentTool {
PublishedAgentTool {
workspace_id: WorkspaceId::new("ws_test"),
workspace_slug: "ws-test".to_owned(),
agent_id: "agent_test".into(),
agent_slug: "agent".to_owned(),
operation: Operation {
id: OperationId::new(format!("op_{name}")),
name: name.to_owned(),
display_name: title.to_owned(),
category: "test".to_owned(),
protocol: Protocol::Rest,
security_level: OperationSecurityLevel::Standard,
status: OperationStatus::Published,
version,
target: Target::Rest(RestTarget {
base_url: "https://example.test".to_owned(),
method: HttpMethod::Get,
path_template: "/leads".to_owned(),
static_headers: BTreeMap::new(),
request_contract: None,
response_contract: Vec::new(),
multipart_field_mime_types: BTreeMap::new(),
}),
input_schema: empty_object_schema(),
output_schema: empty_object_schema(),
input_mapping: MappingSet { rules: Vec::new() },
output_mapping: MappingSet { rules: Vec::new() },
execution_config: ExecutionConfig {
timeout_ms: 10_000,
retry_policy: None,
response_cache: None,
idempotency: None,
safety: None,
approval_policy: None,
auth_profile_ref: None,
headers: BTreeMap::new(),
},
tool_description: ToolDescription {
title: title.to_owned(),
description: description.to_owned(),
tags: Vec::new(),
examples: Vec::new(),
},
samples: None,
generated_draft: None,
config_export: None,
wizard_state: None,
created_at: OffsetDateTime::UNIX_EPOCH,
updated_at: OffsetDateTime::UNIX_EPOCH,
published_at: None,
},
tool_name: name.to_owned(),
tool_title: title.to_owned(),
tool_description: description.to_owned(),
}
}
#[test]
fn a_committed_resource_binding_is_a_resource_change_only() {
let before = CatalogFingerprint::of(&catalog(&[("res_a", 1)], &[("prm_a", 1)], "rev-1"));
@@ -61,7 +172,8 @@ fn a_committed_resource_binding_is_a_resource_change_only() {
after.changes_since(&before),
Signals {
resources: true,
prompts: false
prompts: false,
tools: false
}
);
assert!(!before.changes_since(&after).prompts);
@@ -69,7 +181,8 @@ fn a_committed_resource_binding_is_a_resource_change_only() {
before.changes_since(&after),
Signals {
resources: true,
prompts: false
prompts: false,
tools: false
}
);
}
@@ -83,7 +196,8 @@ fn a_committed_prompt_binding_is_a_prompt_change_only() {
after.changes_since(&before),
Signals {
resources: false,
prompts: true
prompts: true,
tools: false
}
);
}
@@ -97,15 +211,219 @@ fn a_pinned_version_bump_is_a_change_even_when_the_binding_names_are_stable() {
after.changes_since(&before),
Signals {
resources: true,
prompts: false
prompts: false,
tools: false
}
);
}
#[test]
fn a_tool_only_catalog_commit_is_silent() {
// `catalog_revision` moved, but the visible Resource/Prompt projection did not: a Tool-only
// commit must not produce a Resource or Prompt list-change signal.
fn a_committed_tool_definition_change_is_a_tool_change_only() {
let lead = || published_tool("crm_create_lead", "Create Lead", "Creates a lead", 1);
let before = CatalogFingerprint::of(&catalog_with(
ToolSelectionPolicy::default(),
vec![lead()],
&[("res_a", 1)],
&[("prm_a", 1)],
"rev-1",
));
let added = CatalogFingerprint::of(&catalog_with(
ToolSelectionPolicy::default(),
vec![
lead(),
published_tool(
"crm_create_second",
"Create Second",
"Creates a second lead",
1,
),
],
&[("res_a", 1)],
&[("prm_a", 1)],
"rev-2",
));
let retitled = CatalogFingerprint::of(&catalog_with(
ToolSelectionPolicy::default(),
vec![published_tool(
"crm_create_lead",
"Create a lead",
"Creates a lead",
1,
)],
&[("res_a", 1)],
&[("prm_a", 1)],
"rev-2",
));
let tools_only = Signals {
resources: false,
prompts: false,
tools: true,
};
assert_eq!(added.changes_since(&before), tools_only);
assert_eq!(
retitled.changes_since(&before),
tools_only,
"a retitled binding changes the visible Tool projection without a new Operation version"
);
// The reverse direction is a Tool change as well: a removed binding is a real change.
assert!(before.changes_since(&added).tools);
}
#[test]
fn a_republished_operation_version_with_an_identical_definition_is_silent() {
// `tools/list` serves the definition, not the Operation version: a version bump that leaves the
// served definition unchanged is not a client-visible Tool catalog change.
let before = CatalogFingerprint::of(&catalog_with(
ToolSelectionPolicy::default(),
vec![published_tool(
"crm_create_lead",
"Create Lead",
"Creates a lead",
1,
)],
&[("res_a", 1)],
&[("prm_a", 1)],
"rev-1",
));
let after = CatalogFingerprint::of(&catalog_with(
ToolSelectionPolicy::default(),
vec![published_tool(
"crm_create_lead",
"Create Lead",
"Creates a lead",
2,
)],
&[("res_a", 1)],
&[("prm_a", 1)],
"rev-2",
));
assert!(!after.changes_since(&before).any());
}
#[test]
fn a_policy_only_commit_that_changes_tools_list_is_a_tool_change_only() {
// The Tool selection policy is part of the served `tools/list` projection: switching the same
// bindings from direct to search mode replaces the served tools with `search_tools`/`call_tool`.
let tool = published_tool("crm_create_lead", "Create Lead", "Creates a lead", 1);
let direct = CatalogFingerprint::of(&catalog_with(
ToolSelectionPolicy::default(),
vec![tool.clone()],
&[("res_a", 1)],
&[("prm_a", 1)],
"rev-1",
));
let search = CatalogFingerprint::of(&catalog_with(
search_policy(&["crm_create_lead"]),
vec![tool],
&[("res_a", 1)],
&[("prm_a", 1)],
"rev-2",
));
let tools_only = Signals {
resources: false,
prompts: false,
tools: true,
};
assert_eq!(search.changes_since(&direct), tools_only);
assert_eq!(direct.changes_since(&search), tools_only);
}
#[test]
fn a_policy_field_invisible_to_tools_list_is_silent() {
// `search.max_results` is only served inside the search-mode definitions: in direct mode it
// changes nothing the client receives.
let tool = || published_tool("crm_create_lead", "Create Lead", "Creates a lead", 1);
let before = CatalogFingerprint::of(&catalog_with(
ToolSelectionPolicy::default(),
vec![tool()],
&[],
&[],
"rev-1",
));
let after = CatalogFingerprint::of(&catalog_with(
ToolSelectionPolicy {
search: ToolSearchSettings { max_results: 5 },
..ToolSelectionPolicy::default()
},
vec![tool()],
&[],
&[],
"rev-2",
));
assert!(!after.changes_since(&before).any());
}
#[test]
fn a_search_mode_binding_change_is_silent_when_tools_list_is_unchanged() {
// In search mode the served list is `search_tools`/`call_tool`; the bindings behind it are not
// part of `tools/list`, so a binding-only commit must not claim a visible Tool change.
let policy = search_policy(&["crm_create_lead"]);
let before = CatalogFingerprint::of(&catalog_with(
policy.clone(),
vec![published_tool(
"crm_create_lead",
"Create Lead",
"Creates a lead",
1,
)],
&[],
&[],
"rev-1",
));
let after = CatalogFingerprint::of(&catalog_with(
policy,
vec![
published_tool("crm_create_lead", "Create Lead", "Creates a lead", 1),
published_tool(
"crm_create_second",
"Create Second",
"Creates a second lead",
1,
),
],
&[],
&[],
"rev-2",
));
assert!(!after.changes_since(&before).any());
}
#[test]
fn a_resource_or_prompt_change_is_not_a_tool_change() {
let tool = || published_tool("crm_create_lead", "Create Lead", "Creates a lead", 1);
let before = CatalogFingerprint::of(&catalog_with(
ToolSelectionPolicy::default(),
vec![tool()],
&[("res_a", 1)],
&[("prm_a", 1)],
"rev-1",
));
let changed = CatalogFingerprint::of(&catalog_with(
ToolSelectionPolicy::default(),
vec![tool()],
&[("res_a", 2)],
&[("prm_a", 1), ("prm_b", 1)],
"rev-1",
));
assert_eq!(
changed.changes_since(&before),
Signals {
resources: true,
prompts: true,
tools: false
}
);
}
#[test]
fn a_catalog_revision_bump_without_a_visible_change_is_silent() {
// `catalog_revision` moved, but no visible Resource/Prompt/Tool projection did: no signal.
let before = CatalogFingerprint::of(&catalog(&[("res_a", 1)], &[("prm_a", 1)], "rev-1"));
let after = CatalogFingerprint::of(&catalog(&[("res_a", 1)], &[("prm_a", 1)], "rev-2"));
@@ -130,13 +448,14 @@ fn the_projection_is_order_independent_and_has_no_duplicate_growth() {
#[test]
fn the_legacy_frames_carry_a_closed_method_name_and_no_parameters() {
let frames = Wire::Legacy.signal_frames(Signals::BOTH);
let frames = Wire::Legacy.signal_frames(Signals::ALL);
assert_eq!(
frames,
vec![
json!({"jsonrpc": "2.0", "method": RESOURCE_LIST_CHANGED}).to_string(),
json!({"jsonrpc": "2.0", "method": PROMPT_LIST_CHANGED}).to_string(),
json!({"jsonrpc": "2.0", "method": TOOL_LIST_CHANGED}).to_string(),
]
);
// No URI, name or payload of a changed object is part of a list-change notification.
@@ -146,7 +465,7 @@ fn the_legacy_frames_carry_a_closed_method_name_and_no_parameters() {
#[test]
fn the_modern_frames_carry_the_subscription_id_of_their_listen_request() {
let id = json!(41);
let frames = Wire::Modern(id.clone()).signal_frames(Signals::BOTH);
let frames = Wire::Modern(id.clone()).signal_frames(Signals::ALL);
assert_eq!(
frames,
@@ -163,6 +482,12 @@ fn the_modern_frames_carry_the_subscription_id_of_their_listen_request() {
"params": { "_meta": { SUBSCRIPTION_ID_KEY: 41 } }
})
.to_string(),
json!({
"jsonrpc": "2.0",
"method": TOOL_LIST_CHANGED,
"params": { "_meta": { SUBSCRIPTION_ID_KEY: 41 } }
})
.to_string(),
]
);
assert_eq!(
@@ -176,6 +501,7 @@ fn only_the_requested_and_honoured_types_are_encoded() {
let frames = Wire::Modern(json!(1)).signal_frames(Signals {
resources: false,
prompts: true,
tools: false,
});
assert_eq!(frames.len(), 1);
@@ -189,6 +515,7 @@ fn the_acknowledgment_reports_exactly_the_honoured_subset() {
Signals {
resources: true,
prompts: false,
tools: true,
},
))
.unwrap();
@@ -197,7 +524,7 @@ fn the_acknowledgment_reports_exactly_the_honoured_subset() {
assert_eq!(frame["params"]["_meta"][SUBSCRIPTION_ID_KEY], json!(7));
assert_eq!(
frame["params"]["notifications"],
json!({ "resourcesListChanged": true })
json!({ "resourcesListChanged": true, "toolsListChanged": true })
);
}
@@ -224,8 +551,10 @@ fn the_filter_keeps_only_the_implemented_list_change_types() {
signals,
Signals {
resources: false,
prompts: true
}
prompts: true,
tools: true
},
"the honoured set is the requested list-change subset: {signals:?}"
),
FilterOutcome::Invalid(detail) => panic!("a bounded filter must be accepted: {detail}"),
}
@@ -372,7 +701,7 @@ async fn a_failed_catalog_read_is_observable_and_loses_no_committed_change() {
Watch {
workspace_slug: "workspace-canary".to_owned(),
agent_slug: "agent-canary".to_owned(),
signals: Signals::BOTH,
signals: Signals::ALL,
wire: Wire::Legacy,
legacy_stream: None,
deadline: Some(Instant::now() + Duration::from_millis(2_100)),
+1 -1
View File
@@ -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) {
+1 -1
View File
@@ -3,7 +3,7 @@
{
"kind": "inventory",
"path": "docs/capability-inventory.json",
"sha256": "10ca3538aa1b6b25868f80e19932c7ef918398c4817c52bc1aae52f18c31522b"
"sha256": "98b1f3a7f3c8e9ca1bc15bef8b73b360fbd47a42acaef2e0dffb149e2f46687d"
},
{
"kind": "required_surfaces",
+2 -1
View File
@@ -984,7 +984,7 @@
{
"advertised": {
"tools": {
"listChanged": false
"listChanged": true
}
},
"applicability": "stable",
@@ -993,6 +993,7 @@
"kind": "capability",
"open_subfeatures": false,
"owner": "community-release",
"reason": "the adapter emits `notifications/tools/list_changed` from the committed published Tool bindings of the Agent snapshot since Story 3.5; `tools/list` stays authoritative for a client that misses the notification",
"requirement": "FR-13",
"revisions": [
"2026-07-28",
+14 -4
View File
@@ -40,8 +40,18 @@ run_atdd "MCP log level vocabulary" -p crank-community-mcp --lib protocol::loggi
run_atdd "MCP safe logging" -p mcp-server --test integration mcp_logging -- --test-threads=1
run_atdd "capability inventory projection" -p mcp-server --test integration inventory_projection -- --test-threads=1
# Story 3.19 (FR-19): a committed Resource/Prompt catalog change is announced to the client that
# asked for the signal, in both revisions, and the authoritative list methods stay the recovery path.
# 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
# Story 3.19 (FR-19) and Story 3.5 (FR-14): a committed Resource/Prompt/Tool catalog change is
# announced to the client that asked for the signal, in both revisions, and the authoritative list
# methods (including `tools/list`) stay the recovery path. The advertisement projection is covered by
# the `inventory_projection` entry above.
run_atdd "Resource/Prompt/Tool 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
run_atdd "capability advertisement registry" -p crank-community-mcp --lib protocol::registry -- --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
@@ -1 +1 @@
{"completions":{},"logging":{},"prompts":{"listChanged":true},"resources":{"listChanged":true,"subscribe":false},"tools":{"listChanged":false}}
{"completions":{},"logging":{},"prompts":{"listChanged":true},"resources":{"listChanged":true,"subscribe":false},"tools":{"listChanged":true}}
@@ -1,7 +1,7 @@
{
"revision": "2025-11-25",
"inventory_path": "docs/capability-inventory.json",
"inventory_sha256": "10ca3538aa1b6b25868f80e19932c7ef918398c4817c52bc1aae52f18c31522b",
"inventory_sha256": "98b1f3a7f3c8e9ca1bc15bef8b73b360fbd47a42acaef2e0dffb149e2f46687d",
"rule": "remaining-ac-spec.md#5-server-only-projection-rules-1-4",
"projection_inputs": [
{
@@ -1 +1 @@
{"completions":{},"logging":{},"prompts":{"listChanged":true},"resources":{"listChanged":true,"subscribe":false},"tools":{"listChanged":false}}
{"completions":{},"logging":{},"prompts":{"listChanged":true},"resources":{"listChanged":true,"subscribe":false},"tools":{"listChanged":true}}
@@ -1,7 +1,7 @@
{
"revision": "2026-07-28",
"inventory_path": "docs/capability-inventory.json",
"inventory_sha256": "10ca3538aa1b6b25868f80e19932c7ef918398c4817c52bc1aae52f18c31522b",
"inventory_sha256": "98b1f3a7f3c8e9ca1bc15bef8b73b360fbd47a42acaef2e0dffb149e2f46687d",
"rule": "remaining-ac-spec.md#5-server-only-projection-rules-1-4",
"projection_inputs": [
{
@@ -1,6 +1,6 @@
{
"oracle": "crank-current-scope-advertised-capabilities",
"note": "Independent expected projection of the capability descriptor the CURRENT scope is allowed to advertise: advertisement equals what is implemented. Later capabilities are deferred and must not appear until their owning story implements them. This is a scoped projection, not the official MCP capability list. Story 3.19 implements the Resource/Prompt list-change signals, so both listChanged leaves are advertised; URI-content subscriptions stay unimplemented.",
"note": "Independent expected projection of the capability descriptor the CURRENT scope is allowed to advertise: advertisement equals what is implemented. Later capabilities are deferred and must not appear until their owning story implements them. This is a scoped projection, not the official MCP capability list. Story 3.19 implements the Resource/Prompt list-change signals and Story 3.5 the Tools one, so every listChanged leaf is advertised; URI-content subscriptions stay unimplemented.",
"expected_keys": ["completions", "logging", "prompts", "resources", "tools"],
"expected_descriptor": {
"completions": {},
@@ -13,7 +13,7 @@
"subscribe": false
},
"tools": {
"listChanged": false
"listChanged": true
}
},
"must_not_be_advertised": ["experimental", "extensions"],
@@ -47,14 +47,14 @@ EXPECTED_FROZEN = (
b'{"resources":{"listChanged":false,"subscribe":false},"tools":{"listChanged":false}}'
)
EXPECTED_SHA256 = "e38c795fc28fee74168cb045427df55d882f8f7ace206af5c9a3ca4df5892c9a"
# The canonical inventory also implements the logging surface (Story 3.18, FR-19) and the
# Resource/Prompt list-change signals (Story 3.19, FR-19), so the committed oracle and the canonical
# projection carry `logging` next to `completions`/`prompts`/`resources`/`tools`, and both
# `listChanged` leaves are now implemented.
# The canonical inventory also implements the logging surface (Story 3.18, FR-19), the
# Resource/Prompt list-change signals (Story 3.19, FR-19) and the Tools list-change signal
# (Story 3.5, FR-14), so the committed oracle and the canonical projection carry `logging` next to
# `completions`/`prompts`/`resources`/`tools`, and every `listChanged` leaf is now implemented.
COMMITTED_FROZEN = (
b'{"completions":{},"logging":{},"prompts":{"listChanged":true},"resources":{"listChanged":true,"subscribe":false},"tools":{"listChanged":false}}'
b'{"completions":{},"logging":{},"prompts":{"listChanged":true},"resources":{"listChanged":true,"subscribe":false},"tools":{"listChanged":true}}'
)
COMMITTED_SHA256 = "b90b59f32e2e5c43e829b96339b99a52852bc04f48a2ca0ce7e971affa3a878e"
COMMITTED_SHA256 = "7ffa56029595fc84b6ee29930d65eada2b4d7cffd7d76f72a945fe795cabfe0f"
class AdvertisedCapabilitiesProjectionTests(unittest.TestCase):
@@ -1276,9 +1276,9 @@ class Story31FoundationProjectionBoundaryTests(unittest.TestCase):
"""
EXPECTED_FROZEN = (
b'{"completions":{},"logging":{},"prompts":{"listChanged":true},"resources":{"listChanged":true,"subscribe":false},"tools":{"listChanged":false}}'
b'{"completions":{},"logging":{},"prompts":{"listChanged":true},"resources":{"listChanged":true,"subscribe":false},"tools":{"listChanged":true}}'
)
EXPECTED_FROZEN_SHA256 = "b90b59f32e2e5c43e829b96339b99a52852bc04f48a2ca0ce7e971affa3a878e"
EXPECTED_FROZEN_SHA256 = "7ffa56029595fc84b6ee29930d65eada2b4d7cffd7d76f72a945fe795cabfe0f"
def test_control_committed_frozen_oracle_is_the_canonical_projection(self) -> None:
"""Positive control (existing GREEN, AT-13): the committed frozen bytes are canonical."""