Compare commits
3
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
4e7440f25e | ||
|
|
44774883a0 | ||
|
|
a0365bb80b |
No files matched your search
@@ -11,6 +11,12 @@ on:
|
||||
options: [story, feature]
|
||||
default: story
|
||||
required: true
|
||||
deploy_target:
|
||||
description: Deployment target for this run
|
||||
type: choice
|
||||
options: [none, production]
|
||||
default: none
|
||||
required: true
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
@@ -499,7 +505,7 @@ jobs:
|
||||
runs-on: ubuntu-latest
|
||||
needs:
|
||||
- required-checks
|
||||
if: ${{ gitea.event_name == 'push' && gitea.ref == 'refs/heads/main' }}
|
||||
if: ${{ gitea.event_name == 'workflow_dispatch' && gitea.ref == 'refs/heads/main' && inputs.validation_level == 'feature' && inputs.deploy_target == 'production' }}
|
||||
env:
|
||||
REGISTRY: git.itexp.me
|
||||
IMAGE_TAG: ${{ gitea.sha }}
|
||||
|
||||
@@ -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;
|
||||
}
|
||||
@@ -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,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)),
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
{
|
||||
"kind": "inventory",
|
||||
"path": "docs/capability-inventory.json",
|
||||
"sha256": "10ca3538aa1b6b25868f80e19932c7ef918398c4817c52bc1aae52f18c31522b"
|
||||
"sha256": "98b1f3a7f3c8e9ca1bc15bef8b73b360fbd47a42acaef2e0dffb149e2f46687d"
|
||||
},
|
||||
{
|
||||
"kind": "required_surfaces",
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -18,8 +18,9 @@ feature jobs должны быть `skipped` для story и `success` для fe
|
||||
У Crank и FreeHub полный Rust clippy/workspace test и тяжёлые feature/security
|
||||
проверки выполняются только на feature. UI build и быстрые UI unit tests остаются
|
||||
на story, Playwright E2E — на feature. Crank image build/scan/compose smoke — на
|
||||
feature; фактический Deploy остаётся отдельным push-main job со своими build,
|
||||
scan, health и требованием успешного SHA. Тег релиза по умолчанию запускает story
|
||||
feature; фактический Deploy запускается только явным workflow_dispatch на main
|
||||
с validation_level=feature и deploy_target=production после успешных feature gates.
|
||||
Обычный merge/push не выкатывает production. Порядок: delivery-and-deploy.md. Тег релиза по умолчанию запускает story
|
||||
ATDD, сборку бинарных/UI артефактов, security audit и image scan. Полный release
|
||||
clippy/workspace/E2E доступен через ручной dispatch с `validation_level: feature`;
|
||||
отчёт evidence прикладывается только если такой E2E был выполнен. FreeHub
|
||||
|
||||
@@ -0,0 +1,60 @@
|
||||
# Delivery и production deploy
|
||||
|
||||
## Разделение merge и выкатки
|
||||
|
||||
Push в `main` запускает только source CI: story-проверки, UI build и
|
||||
`Required Checks`. Он не запускает production deploy и не загружает секреты
|
||||
OpenBao. PR, метка `feature-ready`, story dispatch и dispatch без явно выбранного
|
||||
production также не выкатывают production.
|
||||
|
||||
Production deploy выполняет только job `Deploy` workflow `CI` и только при
|
||||
одновременном выполнении условий:
|
||||
|
||||
- событие `workflow_dispatch`;
|
||||
- ref `refs/heads/main`;
|
||||
- `validation_level: feature`;
|
||||
- `deploy_target: production`;
|
||||
- успешный `Required Checks`, включая feature jobs `Rust Feature Validation`,
|
||||
`Frontend E2E` и `Community Image Smoke`.
|
||||
|
||||
Любая другая комбинация оставляет deploy пропущенным, поэтому принятый merge в
|
||||
`main` больше не блокируется ожиданием production-выкатки.
|
||||
|
||||
## Ручной запуск
|
||||
|
||||
В Gitea UI: `Actions` -> workflow `CI` -> `Run workflow`.
|
||||
|
||||
Указать точные входные значения:
|
||||
|
||||
| Input | Значение | Обязателен |
|
||||
| --- | --- | --- |
|
||||
| Branch / ref | `main` | да |
|
||||
| `validation_level` | `feature` | да |
|
||||
| `deploy_target` | `production` | да |
|
||||
|
||||
`validation_level: story`, `deploy_target: none` или отсутствие `deploy_target`
|
||||
дают только source CI либо feature-проверки без deploy. Нельзя запускать
|
||||
production deploy из PR, с другой ветки или через push в `main`.
|
||||
|
||||
## Approval и runbook
|
||||
|
||||
Сам по себе ручной dispatch не является автоматическим разрешением на
|
||||
production. Перед запуском release owner или DevOps явно подтверждает:
|
||||
|
||||
1. SHA совпадает с принятым и проверенным коммитом в `main`.
|
||||
2. `Required Checks` для этого SHA успешны, включая feature jobs.
|
||||
3. Пройдены [production checklist](../production-checklist.md) и актуальный
|
||||
[deploy and staging smoke](../deploy-and-staging-smoke.md); известен порядок
|
||||
rollback и проверено наличие backup.
|
||||
4. Нет незапланированных изменений секретов, миграций или инфраструктуры.
|
||||
|
||||
После deploy проверить health endpoints и authenticated product smoke, затем
|
||||
зафиксировать результат в staging/production regression notes. Секреты OpenBao
|
||||
загружаются только внутри уже разрешённого job `Deploy`; не выводить их в логи и
|
||||
не передавать в PR или dispatch story.
|
||||
|
||||
## Ограничения
|
||||
|
||||
Workflow `Community Release` для тегов остаётся отдельным процессом публикации
|
||||
release-образов и не является заменой этому ручному production deploy. Изменение
|
||||
`ci.yml` не даёт постоянного разрешения на выкатку и не меняет приложение.
|
||||
@@ -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
@@ -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
-1
@@ -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
@@ -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
-1
@@ -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"],
|
||||
|
||||
@@ -0,0 +1,201 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[2]
|
||||
WORKFLOW = ROOT / ".gitea" / "workflows" / "ci.yml"
|
||||
|
||||
|
||||
def workflow_text() -> str:
|
||||
return WORKFLOW.read_text(encoding="utf-8")
|
||||
|
||||
|
||||
def job_block(name: str) -> str:
|
||||
lines = workflow_text().splitlines()
|
||||
start = None
|
||||
for index, line in enumerate(lines):
|
||||
if line == f" {name}:":
|
||||
start = index
|
||||
break
|
||||
if start is None:
|
||||
raise AssertionError(f"job {name!r} not found")
|
||||
end = len(lines)
|
||||
for index in range(start + 1, len(lines)):
|
||||
if re.match(r"^ [A-Za-z0-9_-]+:\s*$", lines[index]):
|
||||
end = index
|
||||
break
|
||||
return "\n".join(lines[start:end])
|
||||
|
||||
|
||||
def deploy_guard() -> str:
|
||||
match = re.search(r"(?m)^ if:\s*(.+)$", job_block("deploy"))
|
||||
if match is None:
|
||||
raise AssertionError("deploy job has no guard")
|
||||
return match.group(1).strip()
|
||||
|
||||
|
||||
def guard_conditions() -> dict[str, str]:
|
||||
expression = deploy_guard()
|
||||
if expression.startswith("${{") and expression.endswith("}}"):
|
||||
expression = expression[3:-2].strip()
|
||||
conditions: dict[str, str] = {}
|
||||
for part in expression.split("&&"):
|
||||
match = re.fullmatch(
|
||||
r"([A-Za-z0-9_.]+)\s*==\s*['\"]([^'\"]+)['\"]", part.strip()
|
||||
)
|
||||
if match is None:
|
||||
raise AssertionError(f"unsupported deploy guard condition: {part!r}")
|
||||
conditions[match.group(1)] = match.group(2)
|
||||
return conditions
|
||||
|
||||
|
||||
def deploys(context: dict[str, str | None]) -> bool:
|
||||
return all(
|
||||
context.get(condition) == expected
|
||||
for condition, expected in guard_conditions().items()
|
||||
)
|
||||
|
||||
|
||||
def dispatch_input(name: str) -> str:
|
||||
match = re.search(
|
||||
rf"(?m)^ {re.escape(name)}:\n((?: .*\n)+)", workflow_text()
|
||||
)
|
||||
if match is None:
|
||||
raise AssertionError(f"workflow_dispatch input {name!r} not found")
|
||||
return match.group(0)
|
||||
|
||||
|
||||
class DeployPolicyTests(unittest.TestCase):
|
||||
def test_guard_allows_only_manual_production_feature_on_main(self):
|
||||
self.assertEqual(
|
||||
guard_conditions(),
|
||||
{
|
||||
"gitea.event_name": "workflow_dispatch",
|
||||
"gitea.ref": "refs/heads/main",
|
||||
"inputs.validation_level": "feature",
|
||||
"inputs.deploy_target": "production",
|
||||
},
|
||||
)
|
||||
|
||||
def test_manual_production_feature_on_main_deploys(self):
|
||||
self.assertTrue(
|
||||
deploys(
|
||||
{
|
||||
"gitea.event_name": "workflow_dispatch",
|
||||
"gitea.ref": "refs/heads/main",
|
||||
"inputs.validation_level": "feature",
|
||||
"inputs.deploy_target": "production",
|
||||
}
|
||||
)
|
||||
)
|
||||
|
||||
def test_push_to_main_does_not_deploy(self):
|
||||
self.assertFalse(
|
||||
deploys(
|
||||
{
|
||||
"gitea.event_name": "push",
|
||||
"gitea.ref": "refs/heads/main",
|
||||
"inputs.validation_level": "feature",
|
||||
"inputs.deploy_target": "production",
|
||||
}
|
||||
)
|
||||
)
|
||||
|
||||
def test_pull_request_with_feature_label_does_not_deploy(self):
|
||||
self.assertFalse(
|
||||
deploys(
|
||||
{
|
||||
"gitea.event_name": "pull_request",
|
||||
"gitea.ref": "refs/pull/42/head",
|
||||
"inputs.validation_level": "feature",
|
||||
"inputs.deploy_target": "production",
|
||||
"gitea.event.pull_request.labels.*.name": "feature-ready",
|
||||
}
|
||||
)
|
||||
)
|
||||
|
||||
def test_missing_or_none_deploy_target_does_not_deploy(self):
|
||||
base = {
|
||||
"gitea.event_name": "workflow_dispatch",
|
||||
"gitea.ref": "refs/heads/main",
|
||||
"inputs.validation_level": "feature",
|
||||
}
|
||||
self.assertFalse(deploys(base))
|
||||
self.assertFalse(deploys({**base, "inputs.deploy_target": "none"}))
|
||||
|
||||
def test_story_dispatch_does_not_deploy(self):
|
||||
self.assertFalse(
|
||||
deploys(
|
||||
{
|
||||
"gitea.event_name": "workflow_dispatch",
|
||||
"gitea.ref": "refs/heads/main",
|
||||
"inputs.validation_level": "story",
|
||||
"inputs.deploy_target": "production",
|
||||
}
|
||||
)
|
||||
)
|
||||
|
||||
def test_dispatch_on_other_ref_does_not_deploy(self):
|
||||
self.assertFalse(
|
||||
deploys(
|
||||
{
|
||||
"gitea.event_name": "workflow_dispatch",
|
||||
"gitea.ref": "refs/heads/release",
|
||||
"inputs.validation_level": "feature",
|
||||
"inputs.deploy_target": "production",
|
||||
}
|
||||
)
|
||||
)
|
||||
|
||||
def test_deploy_target_is_explicit_choice_defaulting_to_none(self):
|
||||
block = dispatch_input("deploy_target")
|
||||
self.assertIn("type: choice", block)
|
||||
self.assertIn("options: [none, production]", block)
|
||||
self.assertIn("default: none", block)
|
||||
self.assertIn("required: true", block)
|
||||
|
||||
def test_push_main_source_ci_stays_enabled(self):
|
||||
self.assertRegex(
|
||||
workflow_text(),
|
||||
r"(?m)^ push:\n branches:\n - main$",
|
||||
)
|
||||
|
||||
def test_deploy_requires_successful_required_checks(self):
|
||||
deploy = job_block("deploy")
|
||||
self.assertRegex(deploy, r"(?ms)^ needs:\n - required-checks$")
|
||||
|
||||
def test_required_checks_gate_feature_jobs(self):
|
||||
block = job_block("required-checks")
|
||||
for job in ("rust-feature", "frontend-e2e", "deployment"):
|
||||
self.assertIn(f" - {job}", block)
|
||||
for variable in ("RUST_FEATURE_RESULT", "E2E_RESULT", "IMAGE_RESULT"):
|
||||
self.assertIn(variable, block)
|
||||
|
||||
def test_only_deploy_loads_production_secrets(self):
|
||||
text = workflow_text()
|
||||
self.assertEqual(text.count("scripts/load-openbao-env.sh"), 1)
|
||||
self.assertIn("scripts/load-openbao-env.sh", job_block("deploy"))
|
||||
self.assertNotIn("openbao", job_block("deployment").lower())
|
||||
|
||||
def test_deploy_keeps_build_scan_backup_health_and_smoke_steps(self):
|
||||
deploy = job_block("deploy")
|
||||
for step in (
|
||||
"Load deployment secrets from OpenBao",
|
||||
"Build and push images",
|
||||
"Save deploy image scan evidence",
|
||||
"Sync deployment files to server",
|
||||
"Write environment file",
|
||||
"Validate required environment variables",
|
||||
"Deploy with Docker Compose",
|
||||
"Verify health endpoints",
|
||||
"Run authenticated product smoke",
|
||||
):
|
||||
self.assertIn(f"name: {step}", deploy)
|
||||
self.assertIn("scripts/scan-images.sh", deploy)
|
||||
self.assertIn("deploy-community.sh", deploy)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -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."""
|
||||
|
||||
Reference in new issue
Block a user