tool-provider 0.7.3: send content/v1 only to routes whose consumer declares it

A tool could opt into content/v1 result bodies, but a provider had no way
to tell whether the consumer reads them, so opting in would break every
consumer that still reads the legacy body. A consumer that decodes
content/v1 now declares it in route.open consumer_capabilities, which the
daemon relays on the bind. A provider sends a content/v1 body only on such
a route and the legacy body everywhere else. consumer_reads_content_v1()
makes that check. The conformance case makes the same call on both kinds of
route, and a fake provider that ignores the declaration fails it by name.

Author: ualtinok

Cargo.lock

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.7.2
+
+- Require cortexkit-role-tool-provider 0.7.3 and verify content/v1 results are
+  sent only on routes whose consumer declares that format.
+- Exercise the same content/v1 tool call over legacy and content/v1 routes;
+  reject content/v1 bodies sent to consumers that did not declare support.
+
 ## 0.7.1
 
 - Require cortexkit-role-tool-provider 0.7.1 and add the catalog-gated

crates/cortexkit-role-tool-provider-conformance/CHANGELOG.md

@@ -8,7 +8,7 @@
 # flags.
 [package]
 name = "cortexkit-role-tool-provider-conformance"
-version = "0.7.1"
+version = "0.7.2"
 edition.workspace = true
 license.workspace = true
 repository.workspace = true
@@ -19,7 +19,7 @@ publish = true
 [dependencies]
 async-trait = "0.1"
 cortexkit-role-harness = { version = "0.1.0", path = "../cortexkit-role-harness" }
-cortexkit-role-tool-provider = { version = "0.7.1", path = "../cortexkit-role-tool-provider" }
+cortexkit-role-tool-provider = { version = "0.7.3", path = "../cortexkit-role-tool-provider" }
 futures-util = { version = "0.3", default-features = false }
 serde_json = "1"
 subc-protocol = "0.31"

crates/cortexkit-role-tool-provider-conformance/Cargo.toml

@@ -21,11 +21,20 @@ unknown format strings do not opt in.
 `content_v1_calls()` supplies promptly completing `(tool name, arguments)`
 probes for every declared tool. The default is `[quick_call()]`; override it
 when other tools opt in, and supply multiple probes to check success and
-tool-level error bodies. A missing probe fails by tool name. The case uses
-the real route, decodes each reply as `ToolResult`, and runs `validate`;
-it also checks the entire serialized JSON body's size before decoding so
-unmodeled extensions cannot evade the 3 MiB bound. Malformed replies fail
-by case, tool and member, not as an opaque success.
+tool-level error bodies. A missing probe fails by tool name. For every probe,
+the case makes the same call over a route with no consumer declaration and
+over a route whose bind declares `content/v1`. The first reply must not decode
+as `ToolResult`; the second must decode and pass `validate`. The opted-in route
+must still list `result_format: "content/v1"` in its catalog. The case also
+checks the entire serialized JSON body's size before decoding so unmodeled
+extensions cannot evade the 3 MiB bound. Malformed replies fail by case, tool
+and member, not as an opaque success.
+
+Subjects with a catalog tool that opts into `content/v1` must implement
+`route_with_consumer_capabilities()` to open the declared route through the
+real route-opening path. The method receives the exact consumer capability
+list to send when opening the route; it must not add that declaration to a
+call body.
 
 ## Per-tool call modes
 

crates/cortexkit-role-tool-provider-conformance/README.md

@@ -109,7 +109,7 @@ pub const CASES: &[CaseSpec] = &[
     CaseSpec {
         name: "tool_result_content_v1_valid",
         requires: &[ContentV1],
-        checks: "every tool declaring result_format content/v1 has probes whose replies decode and validate, including the serialized size bound",
+        checks: "each declared content/v1 tool returns an opaque legacy body to an undeclared route and a valid content/v1 body to a route whose consumer declares support",
     },
     CaseSpec {
         name: "terminal_frame_on_refusal",

crates/cortexkit-role-tool-provider-conformance/src/report.rs

@@ -22,7 +22,7 @@ use cortexkit_role_tool_provider::{
     ops, points,
     result::{validate, ResultFormat, ToolResult, MAX_RESULT_BYTES},
     withdraw::{WithdrawAnswer, TARGET_CALL_KEY_FIELD},
-    CallMode, PROVIDES,
+    CallMode, CONTENT_V1_CAPABILITY, PROVIDES,
 };
 use futures_util::future::join;
 use serde_json::{json, Value};
@@ -326,6 +326,14 @@ where
         self.route(&self.subject.plain_stamp()).await
     }
 
+    async fn consumer_route(&self, consumer_capabilities: &[String]) -> Result<S::Route, String> {
+        let stamp = self.subject.plain_stamp();
+        self.subject
+            .route_with_consumer_capabilities(self.handle.inner(), &stamp, consumer_capabilities)
+            .await
+            .map_err(|e| format!("opening a route with consumer capabilities: {e}"))
+    }
+
     fn principals(&self) -> Result<ScopedPrincipals, String> {
         principals(self.subject)
     }
@@ -359,8 +367,8 @@ where
     }
 
     async fn tool_result_content_v1_valid(&self) -> CaseResult {
-        let route = self.plain_route().await?;
-        let catalog = self.catalog(&route).await?;
+        let legacy_route = self.plain_route().await?;
+        let catalog = self.catalog(&legacy_route).await?;
         let calls = self.subject.content_v1_calls();
         let tools: Vec<_> = catalog
             .tools
@@ -370,7 +378,18 @@ where
         if tools.is_empty() {
             return Err("content/v1 catalog declaration disappeared during the run".into());
         }
+        let capabilities = vec![CONTENT_V1_CAPABILITY.to_owned()];
+        let content_v1_route = self.consumer_route(&capabilities).await?;
+        let opted_in_catalog = self.catalog(&content_v1_route).await?;
         for tool in tools {
+            if !opted_in_catalog.tools.iter().any(|listed| {
+                listed.name == tool.name && listed.result_format == Some(ResultFormat::ContentV1)
+            }) {
+                return Err(format!(
+                    "{}: catalog did not list result_format content/v1 on the declared route",
+                    tool.name
+                ));
+            }
             let probes: Vec<_> = calls
                 .iter()
                 .filter(|(name, _)| name == &tool.name)
@@ -382,10 +401,16 @@ where
                 ));
             }
             for (name, arguments) in probes {
-                let body = expect_response(
-                    name,
-                    request(&route, call_body(name, arguments.clone(), None)).await?,
-                )?;
+                let call = call_body(name, arguments.clone(), None);
+                let legacy_body =
+                    expect_response(name, request(&legacy_route, call.clone()).await?)?;
+                if serde_json::from_value::<ToolResult>(legacy_body).is_ok() {
+                    return Err(format!(
+                        "{name}: route without consumer declaration returned a body decodable as content/v1"
+                    ));
+                }
+
+                let body = expect_response(name, request(&content_v1_route, call).await?)?;
                 let bytes = serde_json::to_vec(&body)
                     .map_err(|e| format!("{name}: reply serialization: {e}"))?;
                 if bytes.len() >= MAX_RESULT_BYTES {

crates/cortexkit-role-tool-provider-conformance/src/runner.rs

@@ -135,6 +135,21 @@ pub trait ToolProviderSubject: Harness {
     /// `tool.catalog` and plain calls.
     fn plain_stamp(&self) -> RouteStamp;
 
+    /// Open a real route whose bind declares the supplied consumer
+    /// capabilities. The adapter must put this list on `route.open` exactly
+    /// as provided; it must not infer the declaration from a call body.
+    /// Required when the catalog declares a `content/v1` tool.
+    async fn route_with_consumer_capabilities(
+        &self,
+        _handle: &Self::Handle,
+        _stamp: &RouteStamp,
+        _consumer_capabilities: &[String],
+    ) -> Result<Self::Route, HarnessError> {
+        Err(HarnessError::new(
+            "no consumer-capability route adapter supplied",
+        ))
+    }
+
     /// The identities for the scoped cases. Required by
     /// [`Capability::ScopeStamp`].
     fn scoped_principals(&self) -> Option<ScopedPrincipals>;

crates/cortexkit-role-tool-provider-conformance/src/subject.rs

@@ -39,7 +39,7 @@ use cortexkit_role_tool_provider_conformance::{
             composition_digest, schema_digest, serves_call_mode, system_text_digest,
             CatalogRequest, CatalogTool,
         },
-        errors,
+        consumer_reads_content_v1, errors,
         late_results::{
             check_since, kinds, reasons, AckRequest, Cursor, LateEntry, LateResultsReply,
             LateResultsRequest,
@@ -128,6 +128,8 @@ pub struct Defects {
     pub opaque_result: bool,
     /// The content/v1 tool replies with structured data but no content parts.
     pub malformed_result: bool,
+    /// Send content/v1 even when the route's bind does not declare support.
+    pub ignore_consumer_capabilities: bool,
 }
 
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
@@ -508,6 +510,7 @@ impl Module {
         &self,
         stamp: &RouteStamp,
         mode: &CallMode,
+        consumer_capabilities: Option<&[String]>,
         body: Value,
     ) -> Result<Vec<ObservedFrame>, RouteFailure> {
         if !self.alive.load(Ordering::SeqCst) {
@@ -565,7 +568,11 @@ impl Module {
         Ok(match name {
             ops::ROLE_DESCRIBE => vec![ObservedFrame::Response(Self::describe())],
             ops::TOOL_CATALOG => reply(self.catalog(&request.arguments)),
-            QUICK if !self.defects.opaque_result => {
+            QUICK
+                if !self.defects.opaque_result
+                    && (self.defects.ignore_consumer_capabilities
+                        || consumer_reads_content_v1(consumer_capabilities)) =>
+            {
                 vec![ObservedFrame::Response(if self.defects.malformed_result {
                     json!({"content": [], "structuredContent": {"only": "program data"}})
                 } else {
@@ -738,13 +745,19 @@ pub struct FakeRoute {
     module: Arc<Module>,
     stamp: RouteStamp,
     mode: CallMode,
+    consumer_capabilities: Option<Vec<String>>,
 }
 
 #[async_trait]
 impl ToolRoute for FakeRoute {
     async fn request(&self, body: Value) -> Result<Exchange, RouteFailure> {
         Ok(Exchange {
-            frames: self.module.handle(&self.stamp, &self.mode, body)?,
+            frames: self.module.handle(
+                &self.stamp,
+                &self.mode,
+                self.consumer_capabilities.as_deref(),
+                body,
+            )?,
         })
     }
 
@@ -846,6 +859,7 @@ impl Harness for FakeSubject {
             module: handle.0.clone(),
             stamp: stamp.clone(),
             mode: CallMode::Classic,
+            consumer_capabilities: None,
         })
     }
 
@@ -932,6 +946,21 @@ impl ToolProviderSubject for FakeSubject {
             module: handle.0.clone(),
             stamp: stamp.clone(),
             mode: mode.clone(),
+            consumer_capabilities: None,
+        })
+    }
+
+    async fn route_with_consumer_capabilities(
+        &self,
+        handle: &FakeHandle,
+        stamp: &RouteStamp,
+        consumer_capabilities: &[String],
+    ) -> Result<FakeRoute, HarnessError> {
+        Ok(FakeRoute {
+            module: handle.0.clone(),
+            stamp: stamp.clone(),
+            mode: CallMode::Classic,
+            consumer_capabilities: Some(consumer_capabilities.to_vec()),
         })
     }
 

crates/cortexkit-role-tool-provider-conformance/tests/fake/mod.rs

@@ -134,6 +134,18 @@ async fn malformed_content_v1_reply_fails_by_case_tool_and_member() {
     assert_passed(&report, "terminal_frame_on_success");
 }
 
+#[tokio::test]
+async fn content_v1_is_sent_only_to_a_route_that_declares_support() {
+    let report = run(&FakeSubject::new(Defects {
+        ignore_consumer_capabilities: true,
+        ..Defects::default()
+    }))
+    .await;
+    let reason = failed(&report, "tool_result_content_v1_valid");
+    assert!(reason.contains("without consumer declaration"), "{reason}");
+    assert_passed(&report, "terminal_frame_on_success");
+}
+
 #[tokio::test]
 async fn opaque_tools_skip_content_v1_by_name_never_pass() {
     let mut subject = FakeSubject::new(Defects {

crates/cortexkit-role-tool-provider-conformance/tests/runner.rs

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.7.3
+
+- Add a route-bind capability constant and helper for detecting consumers that
+  declare support for `content/v1` result bodies.
+- Require providers to choose a tool's `content/v1` or legacy result body from
+  the route bind, and document the consumer's matching declaration.
+
 ## 0.7.2
 
 - Define three more unprefixed capability tags, so a consumer can ask for