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.
This commit is contained in:
hermes-dev authored and bsodfather committed 2026-10-26 17:22:07 +00:00
1 parent 2499016dc7
commit a0365bb80b
17 files changed
+644 -91

No files matched your search

@@ -47,10 +47,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);
@@ -410,6 +413,122 @@ 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;
}
/// 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 +833,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,267 @@ 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-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;
}
@@ -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),
@@ -373,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 {
@@ -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,14 @@
//! 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 binding projection 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 +56,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 +82,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 +120,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 +149,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 +164,7 @@ impl ListenFilter {
FilterOutcome::Accepted(Signals {
resources: self.resources_list_changed,
prompts: self.prompts_list_changed,
tools: self.tools_list_changed,
})
}
}
@@ -173,16 +178,20 @@ 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, Prompt and Tool 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 or Prompt signal, and vice versa — so the three binding vectors
/// 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,33 +201,59 @@ fn acknowledged_filter_wire(accepted: Signals) -> Value {
pub(crate) struct CatalogFingerprint {
resources: Vec<(String, u32)>,
prompts: Vec<(String, u32)>,
/// Tool name, published Operation version and the visible title/description of the binding.
tools: Vec<(String, u32, String, String)>,
}
impl CatalogFingerprint {
pub(crate) fn of(catalog: &PublishedAgentCatalog) -> Self {
let mut resources = catalog
.resources
.iter()
.map(|binding| {
// The bound Tool is the published Operation snapshot of the binding, so its own version is
// part of the visible `tools/list` projection, next to the binding's own title/description.
Self::from_parts(
catalog
.resources
.iter()
.map(|binding| (binding.resource_id.as_str(), binding.resource_version)),
catalog
.prompts
.iter()
.map(|binding| (binding.prompt_id.as_str(), binding.prompt_version)),
catalog.tools.iter().map(|binding| {
(
binding.resource_id.as_str().to_owned(),
binding.resource_version,
binding.tool_name.as_str(),
binding.operation.version,
binding.tool_title.as_str(),
binding.tool_description.as_str(),
)
})
.collect::<Vec<_>>();
let mut prompts = catalog
.prompts
.iter()
.map(|binding| {
}),
)
}
fn from_parts<'a>(
resources: impl Iterator<Item = (&'a str, u32)>,
prompts: impl Iterator<Item = (&'a str, u32)>,
tools: impl Iterator<Item = (&'a str, u32, &'a str, &'a str)>,
) -> Self {
fn sorted<T: Ord>(values: impl Iterator<Item = T>) -> Vec<T> {
let mut sorted = values.collect::<Vec<_>>();
sorted.sort();
sorted
}
fn owned<'a>(values: impl Iterator<Item = (&'a str, u32)>) -> Vec<(String, u32)> {
sorted(values.map(|(name, version)| (name.to_owned(), version)))
}
Self {
resources: owned(resources),
prompts: owned(prompts),
tools: sorted(tools.map(|(name, version, title, description)| {
(
binding.prompt_id.as_str().to_owned(),
binding.prompt_version,
name.to_owned(),
version,
title.to_owned(),
description.to_owned(),
)
})
.collect::<Vec<_>>();
resources.sort();
prompts.sort();
Self { resources, prompts }
})),
}
}
/// The list-change types whose visible binding projection differs between `previous` and `self`.
@@ -226,6 +261,7 @@ impl CatalogFingerprint {
Signals {
resources: self.resources != previous.resources,
prompts: self.prompts != previous.prompts,
tools: self.tools != previous.tools,
}
}
}
@@ -241,10 +277,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;
@@ -18,7 +18,7 @@ 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(
@@ -61,7 +61,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 +70,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 +85,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 +100,100 @@ 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_binding_or_version_is_a_tool_change_only() {
let before = CatalogFingerprint::from_parts(
[("res_a", 1)].into_iter(),
[("prm_a", 1)].into_iter(),
[("crm_create_lead", 1, "Create Lead", "Creates a lead")].into_iter(),
);
let added = CatalogFingerprint::from_parts(
[("res_a", 1)].into_iter(),
[("prm_a", 1)].into_iter(),
[
("crm_create_lead", 1, "Create Lead", "Creates a lead"),
(
"crm_create_second",
1,
"Create Second",
"Creates a second lead",
),
]
.into_iter(),
);
let bumped = CatalogFingerprint::from_parts(
[("res_a", 1)].into_iter(),
[("prm_a", 1)].into_iter(),
[("crm_create_lead", 2, "Create Lead", "Creates a lead")].into_iter(),
);
let retitled = CatalogFingerprint::from_parts(
[("res_a", 1)].into_iter(),
[("prm_a", 1)].into_iter(),
[("crm_create_lead", 1, "Create a lead", "Creates a lead")].into_iter(),
);
assert_eq!(
added.changes_since(&before),
Signals {
resources: false,
prompts: false,
tools: true
}
);
assert_eq!(
bumped.changes_since(&before),
Signals {
resources: false,
prompts: false,
tools: true
},
"a re-published Operation version changes the visible Tool projection"
);
assert_eq!(
retitled.changes_since(&before),
Signals {
resources: false,
prompts: false,
tools: true
},
"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_resource_or_prompt_change_is_not_a_tool_change() {
let before = CatalogFingerprint::from_parts(
[("res_a", 1)].into_iter(),
[("prm_a", 1)].into_iter(),
[("crm_create_lead", 1, "Create Lead", "Creates a lead")].into_iter(),
);
let changed = CatalogFingerprint::from_parts(
[("res_a", 2)].into_iter(),
[("prm_a", 1), ("prm_b", 1)].into_iter(),
[("crm_create_lead", 1, "Create Lead", "Creates a lead")].into_iter(),
);
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 +218,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 +235,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 +252,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 +271,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 +285,7 @@ fn the_acknowledgment_reports_exactly_the_honoured_subset() {
Signals {
resources: true,
prompts: false,
tools: true,
},
))
.unwrap();
@@ -197,7 +294,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 +321,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 +471,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
@@ -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",
+6 -4
View File
@@ -40,11 +40,13 @@ 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,
@@ -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."""