#![cfg(test)]
use super::model::{
Client, ClientTool, CompletionReason, ContentKind, Event, Info, Request, RequestError,
RequestPlan, SamplingParams, StreamError, StreamGrammar, TokenUsage, ToolChoice,
};
use crate::opaque::{Envelope, Payload};
use crate::redact_tests::{SECRET, assert_redacted, assert_states};
use crate::transcript::item::{self, Assistant, Item, ModelVisibility, System, User};
use crate::value::content::{Part, PartFields, PartKind, Segment, SegmentExtensions};
use crate::value::tool_call::{self, Id, ToolCall, ToolResult};
use futures_core::Stream as _;
use std::collections::VecDeque;
use std::error::Error;
use std::fmt;
use std::future::{Future, ready};
use std::pin::Pin;
use std::sync::atomic::{AtomicUsize, Ordering};
use std::task::{Context, Poll, Waker};
fn id(value: &str) -> Id {
Id::new(value.into())
}
fn name(value: &str) -> tool_call::Name {
tool_call::Name::new(value.into())
}
fn payload(value: &[u8]) -> Payload {
Payload::copy_from_slice(value)
}
fn extensions() -> SegmentExtensions {
SegmentExtensions::new(String::new(), None, None)
}
fn call(call_id: &str, tool: &str, arguments: &[u8]) -> ToolCall {
ToolCall::new(id(call_id), name(tool), payload(arguments))
}
fn done() -> Event {
Event::Done {
finish_reason: "stop".into(),
completion: CompletionReason::Stop,
provider_data: Vec::new(),
}
}
fn text_delta(item_id: &str, kind: ContentKind, value: &str) -> Event {
Event::ContentDelta {
id: item_id.into(),
kind,
delta: value.into(),
}
}
fn text_final(item_id: &str, kind: ContentKind, value: &str) -> Event {
Event::ContentFinal {
id: item_id.into(),
kind,
content: value.into(),
extensions: extensions(),
}
}
fn assistant(calls: &[(&str, &str)]) -> Item {
visible_assistant(calls, ModelVisibility::Visible)
}
fn visible_assistant(calls: &[(&str, &str)], visibility: ModelVisibility) -> Item {
let mut content = vec![Segment::Text {
text: "assistant".into(),
extensions: extensions(),
}];
content.extend(calls.iter().map(|(call_id, tool)| Segment::ToolCall {
call: call(call_id, tool, b"{}"),
extensions: extensions(),
}));
Item::Assistant(Assistant::new(content, None).with_visibility(visibility))
}
fn result(call_id: &str, tool: &str, visibility: ModelVisibility) -> Item {
Item::ToolResult(item::ToolResult::new(
id(call_id),
name(tool),
ToolResult::no_output(),
visibility,
None,
))
}
fn user(text: &str, visibility: ModelVisibility) -> Item {
Item::User(User::new(vec![Part::text(text.into())], visibility))
}
fn system(text: &str, visibility: ModelVisibility) -> Item {
Item::System(System::new("instruction".into(), text.into(), visibility))
}
#[test]
fn plan_lanes_are_readable_and_clearable_without_exposing_their_containers() {
let tool = ClientTool::new(name("search"), "Search".into(), payload(b"{}"));
let extension =
|kind: &str| Envelope::try_new("provider".into(), kind.into(), payload(b"{}")).unwrap();
let mut plan = RequestPlan::new();
assert!(plan.system_instruction().is_empty());
assert!(plan.tools().is_empty());
assert!(plan.extensions().is_empty());
assert!(plan.ephemeral().is_empty());
plan.push_system_instruction(Part::text("first".into()))
.extend_system_instruction([Part::text("second".into())])
.push_tool(tool.clone())
.extend_tools([tool.clone()])
.push_extension(extension("one"))
.extend_extensions([extension("two")])
.push_ephemeral(Part::text("hot".into()))
.extend_ephemeral([Part::text("hotter".into())]);
assert_eq!(
plan.system_instruction()
.iter()
.map(|part| part.fields().text())
.collect::<Vec<_>>(),
["first", "second"]
);
assert_eq!(plan.tools().len(), 2);
assert_eq!(plan.tools()[1].name().as_str(), "search");
assert_eq!(
plan.extensions()
.iter()
.map(Envelope::kind)
.collect::<Vec<_>>(),
["one", "two"]
);
assert_eq!(
plan.ephemeral()
.iter()
.map(|part| part.fields().text())
.collect::<Vec<_>>(),
["hot", "hotter"]
);
plan.clear_system_instruction()
.clear_tools()
.clear_extensions()
.clear_ephemeral();
assert!(plan.system_instruction().is_empty());
assert!(plan.tools().is_empty());
assert!(plan.extensions().is_empty());
assert!(plan.ephemeral().is_empty());
let request = plan.try_into_request(Vec::new()).unwrap();
assert!(request.system_instruction().is_empty());
assert!(request.tools().is_empty());
assert!(request.extensions().is_empty());
assert!(request.ephemeral().is_empty());
}
#[test]
fn request_freezes_owned_plan_and_separates_tool_lanes() {
let local = ClientTool::new(
name("search"),
"Search docs".into(),
payload(br#"{"type":"object"}"#),
);
let hosted = Envelope::try_new(
"provider".into(),
"hosted-tool".into(),
payload(br#"{"type":"web"}"#),
)
.unwrap();
let mut plan = RequestPlan::new();
plan.push_system_instruction(Part::new(
PartKind::from_i64(0),
PartFields::new(
"system".into(),
"text/custom".into(),
Some(vec![1, 2].into_boxed_slice()),
"reference".into(),
Some(crate::value::content::Metadata::new()),
Some(payload(b"raw")),
),
));
plan.push_tool(local.clone())
.push_extension(hosted)
.push_ephemeral(Part::text("pressure".into()));
*plan.sampling_mut() = SamplingParams {
temperature: Some(0.5),
reasoning_effort: Some("high".into()),
max_output_tokens: Some(42),
parallel_tool_calls: true,
output_schema: Some(payload(br#"{"type":"string"}"#)),
stop_sequences: vec!["STOP".into()],
tool_choice: Some(ToolChoice::Specific(name("search"))),
};
let request = plan
.try_into_request(vec![system("hello", ModelVisibility::Visible)])
.unwrap();
assert_eq!(request.system_instruction().len(), 1);
let instruction = request.system_instruction()[0].fields();
assert_eq!(instruction.text(), "system");
assert_eq!(instruction.mime(), "text/custom");
assert_eq!(instruction.data(), Some([1, 2].as_slice()));
assert_eq!(instruction.reference(), "reference");
assert!(instruction.metadata().is_some());
assert_eq!(instruction.raw_payload().unwrap().as_bytes(), b"raw");
assert_eq!(request.messages().len(), 1);
assert_eq!(request.tools().len(), 1);
assert_eq!(request.extensions().len(), 1);
assert_eq!(request.ephemeral().len(), 1);
assert_eq!(request.tools()[0].name().as_str(), "search");
assert_eq!(request.tools()[0].description(), "Search docs");
assert_eq!(
request.tools()[0].input_schema().as_bytes(),
br#"{"type":"object"}"#
);
assert_eq!(request.sampling().temperature, Some(0.5));
assert!(request.sampling().parallel_tool_calls);
let cloned_request = request.clone();
assert_eq!(cloned_request.tools()[0].name().as_str(), "search");
assert!(
matches!(request.sampling().tool_choice, Some(ToolChoice::Specific(ref value)) if value.as_str() == "search")
);
let choices = [ToolChoice::Auto, ToolChoice::None, ToolChoice::Required];
assert!(matches!(choices[0], ToolChoice::Auto));
assert!(matches!(choices[1], ToolChoice::None));
assert!(matches!(choices[2], ToolChoice::Required));
let clone = local.clone();
assert_eq!(clone.name().as_str(), "search");
}
#[test]
fn request_rejects_empty_non_text_and_unknown_system_instruction_parts() {
let cases = [
(
Part::text(String::new()),
RequestError::EmptySystemInstructionText { index: 0 },
"system instruction text at index 0 is empty",
),
(
Part::new(
PartKind::from_i64(1),
PartFields::new(
"image".into(),
"image/png".into(),
None,
String::new(),
None,
None,
),
),
RequestError::NonTextSystemInstruction { index: 0, kind: 1 },
"system instruction part at index 0 has non-text kind 1",
),
(
Part::new(
PartKind::from_i64(99),
PartFields::new(
"future".into(),
String::new(),
None,
String::new(),
None,
None,
),
),
RequestError::UnknownSystemInstruction { index: 0, kind: 99 },
"system instruction part at index 0 has unknown kind 99",
),
];
for (part, expected, message) in cases {
let mut plan = RequestPlan::new();
plan.push_system_instruction(part);
let error = plan.try_into_request(Vec::new()).err().unwrap();
assert_eq!(error, expected);
assert_eq!(error.to_string(), message);
assert!(error.source().is_none());
}
let mut plan = RequestPlan::new();
plan.extend_system_instruction([Part::text("valid".into()), Part::text(String::new())]);
assert_eq!(
plan.try_into_request(Vec::new()).err().unwrap(),
RequestError::EmptySystemInstructionText { index: 1 }
);
}
#[test]
fn request_projects_every_user_only_variant_before_validating_tool_exchange() {
let request = RequestPlan::new()
.try_into_request(vec![
user("hidden user", ModelVisibility::Hidden),
system("hidden system", ModelVisibility::Hidden),
assistant(&[("first", "search"), ("second", "read")]),
result("hidden", "ignored", ModelVisibility::Hidden),
result("second", "read", ModelVisibility::Visible),
result("first", "search", ModelVisibility::Visible),
assistant(&[("third", "finish")]),
result("third", "finish", ModelVisibility::Visible),
user("visible user", ModelVisibility::Visible),
])
.unwrap();
assert_eq!(request.messages().len(), 6);
assert!(matches!(request.messages()[0], Item::Assistant(_)));
assert!(matches!(request.messages()[1], Item::ToolResult(_)));
assert!(matches!(request.messages()[2], Item::ToolResult(_)));
assert!(matches!(request.messages()[3], Item::Assistant(_)));
assert!(matches!(request.messages()[4], Item::ToolResult(_)));
assert!(matches!(request.messages()[5], Item::User(_)));
}
#[test]
fn projection_hides_a_whole_exchange_and_leaves_no_user_only_record_in_the_request() {
let request = RequestPlan::new()
.try_into_request(vec![
user("visible user", ModelVisibility::Visible),
visible_assistant(&[("hidden", "search")], ModelVisibility::Hidden),
result("hidden", "search", ModelVisibility::Hidden),
visible_assistant(&[("shown", "read")], ModelVisibility::Visible),
result("shown", "read", ModelVisibility::Visible),
])
.unwrap();
assert_eq!(request.messages().len(), 3);
assert!(matches!(request.messages()[0], Item::User(_)));
assert!(matches!(&request.messages()[1], Item::Assistant(assistant)
if matches!(&assistant.content()[1], Segment::ToolCall { call, .. }
if call.id().as_str() == "shown")));
assert!(matches!(&request.messages()[2], Item::ToolResult(result)
if result.call_id().as_str() == "shown"));
assert!(
request.messages().iter().all(|item| match item {
Item::User(item) => item.visibility() == ModelVisibility::Visible,
Item::Assistant(item) => item.visibility() == ModelVisibility::Visible,
Item::ToolResult(item) => item.visibility() == ModelVisibility::Visible,
Item::System(item) => item.visibility() == ModelVisibility::Visible,
}),
"a provider never has to consult item visibility"
);
}
#[test]
fn projection_refuses_an_exchange_whose_two_halves_disagree_about_visibility() {
let orphan = RequestPlan::new()
.try_into_request(vec![
visible_assistant(&[("call", "search")], ModelVisibility::Hidden),
result("call", "search", ModelVisibility::Visible),
])
.err()
.unwrap();
assert_eq!(
orphan,
RequestError::OrphanToolResult {
call_id: "call".into(),
}
);
let unanswered = RequestPlan::new()
.try_into_request(vec![
visible_assistant(&[("call", "search")], ModelVisibility::Visible),
result("call", "search", ModelVisibility::Hidden),
])
.err()
.unwrap();
assert_eq!(unanswered, RequestError::UnresolvedToolCalls { count: 1 });
}
fn renormalise(request: &Request, rewrite: &dyn Fn(&Segment) -> Segment) -> Request {
let mut plan = RequestPlan::new();
plan.extend_system_instruction(request.system_instruction().iter().cloned())
.extend_tools(request.tools().iter().cloned())
.extend_extensions(request.extensions().iter().cloned())
.extend_ephemeral(request.ephemeral().iter().cloned());
*plan.sampling_mut() = request.sampling().clone();
let messages = request
.messages()
.iter()
.map(|item| match item {
Item::Assistant(assistant) => Item::Assistant(
Assistant::new(
assistant.content().iter().map(rewrite).collect(),
assistant.provider_data().map(<[_]>::to_vec),
)
.with_visibility(assistant.visibility()),
),
other => other.clone(),
})
.collect();
plan.try_into_request(messages)
.expect("a normalised history is still a legal history")
}
#[test]
fn a_before_model_rewrite_can_normalise_foreign_segments_and_lose_no_lane() {
let mut plan = RequestPlan::new();
plan.push_system_instruction(Part::text("be brief".into()))
.push_tool(ClientTool::new(
name("search"),
"Search".into(),
payload(br#"{"type":"object"}"#),
))
.push_extension(
Envelope::try_new("provider".into(), "hosted".into(), payload(b"{}")).unwrap(),
)
.push_ephemeral(Part::text("volatile".into()));
*plan.sampling_mut() = SamplingParams {
temperature: Some(0.25),
stop_sequences: vec!["STOP".into()],
tool_choice: Some(ToolChoice::Required),
..SamplingParams::default()
};
let foreign = Item::Assistant(Assistant::new(
vec![
Segment::Thinking {
text: "private reasoning".into(),
extensions: SegmentExtensions::new(
"vendor-a-signature".into(),
Some(payload(&[1, 2])),
None,
),
},
Segment::Text {
text: "answer".into(),
extensions: extensions(),
},
],
None,
));
let request = plan
.try_into_request(vec![user("ask", ModelVisibility::Visible), foreign])
.unwrap();
let degraded = renormalise(&request, &|segment| match segment {
Segment::Thinking { text, .. } => Segment::Text {
text: format!("<thinking>{text}</thinking>"),
extensions: SegmentExtensions::new(String::new(), None, None),
},
other => other.clone(),
});
let Item::Assistant(rewritten) = °raded.messages()[1] else {
panic!("the assistant record kept its position");
};
assert!(
matches!(&rewritten.content()[0], Segment::Text { text, extensions }
if text == "<thinking>private reasoning</thinking>" && extensions.signature().is_empty())
);
assert!(matches!(&rewritten.content()[1], Segment::Text { text, .. } if text == "answer"));
assert_eq!(degraded.system_instruction().len(), 1);
assert_eq!(degraded.system_instruction()[0].fields().text(), "be brief");
assert_eq!(degraded.tools().len(), 1);
assert_eq!(degraded.tools()[0].name().as_str(), "search");
assert_eq!(degraded.extensions().len(), 1);
assert_eq!(degraded.extensions()[0].kind(), "hosted");
assert_eq!(degraded.sampling().temperature, Some(0.25));
assert_eq!(degraded.sampling().stop_sequences, ["STOP"]);
assert!(matches!(
degraded.sampling().tool_choice,
Some(ToolChoice::Required)
));
assert_eq!(degraded.messages().len(), 2);
assert_eq!(degraded.ephemeral().len(), 1);
assert_eq!(degraded.ephemeral()[0].fields().text(), "volatile");
assert!(
degraded
.messages()
.iter()
.all(|item| !matches!(item, Item::User(user)
if user.parts()[0].fields().text() == "volatile"))
);
}
#[test]
fn request_rejects_invalid_tool_call_id_name_and_global_reuse() {
let cases = [
(
vec![assistant(&[("", "tool")])],
RequestError::EmptyToolCallId,
"assistant tool call id is empty",
),
(
vec![assistant(&[("call", "")])],
RequestError::EmptyToolCallName {
call_id: "call".into(),
},
"assistant tool call call has an empty name",
),
(
vec![
assistant(&[("call", "first")]),
result("call", "first", ModelVisibility::Visible),
assistant(&[("call", "second")]),
],
RequestError::DuplicateToolCallId {
call_id: "call".into(),
},
"duplicate assistant tool call id: call",
),
];
for (items, expected, message) in cases {
let error = RequestPlan::new().try_into_request(items).err().unwrap();
assert_eq!(error, expected);
assert_eq!(error.to_string(), message);
}
}
#[test]
fn request_rejects_invalid_tool_result_identity_pairing_and_eof() {
let cases = [
(
vec![result("", "tool", ModelVisibility::Visible)],
RequestError::EmptyToolResultId,
"tool result call id is empty",
),
(
vec![
assistant(&[("call", "tool")]),
result("call", "", ModelVisibility::Visible),
],
RequestError::EmptyToolResultName {
call_id: "call".into(),
},
"tool result call has an empty name",
),
(
vec![result("orphan", "tool", ModelVisibility::Visible)],
RequestError::OrphanToolResult {
call_id: "orphan".into(),
},
"orphan tool result: orphan",
),
(
vec![
assistant(&[("call", "expected")]),
result("call", "actual", ModelVisibility::Visible),
],
RequestError::ToolResultNameMismatch {
call_id: "call".into(),
expected: "expected".into(),
actual: "actual".into(),
},
"tool result call names actual, expected expected",
),
(
vec![assistant(&[("one", "a"), ("two", "b")])],
RequestError::UnresolvedToolCalls { count: 2 },
"request ends with 2 unresolved tool call(s)",
),
];
for (items, expected, message) in cases {
let error = RequestPlan::new().try_into_request(items).err().unwrap();
assert_eq!(error, expected);
assert_eq!(error.to_string(), message);
}
}
#[test]
fn request_requires_pending_calls_to_close_before_each_boundary_item() {
let boundaries = [
user("next", ModelVisibility::Visible),
system("next", ModelVisibility::Visible),
assistant(&[]),
];
for boundary in boundaries {
let error = RequestPlan::new()
.try_into_request(vec![assistant(&[("call", "tool")]), boundary])
.err()
.unwrap();
assert_eq!(error, RequestError::ToolExchangeNotClosed);
assert_eq!(
error.to_string(),
"message appears before the preceding tool exchange is closed"
);
}
}
#[test]
fn token_usage_is_built_from_two_counts_and_refined_one_field_at_a_time() {
let plain = TokenUsage::new(1_200, 340);
assert_eq!(
plain,
TokenUsage {
prompt: 1_200,
completion: 340,
total: 1_540,
cached: 0,
reasoning: 0,
}
);
let refined = TokenUsage::new(1_200, 340)
.with_total(1_600)
.with_cached(900)
.with_reasoning(210);
assert_eq!(
refined,
TokenUsage {
prompt: 1_200,
completion: 340,
total: 1_600,
cached: 900,
reasoning: 210,
}
);
assert_eq!(
TokenUsage::new(u64::MAX, 1).total,
u64::MAX,
"a total nobody can represent saturates rather than wrapping to nonsense"
);
assert_eq!(TokenUsage::new(0, 0), TokenUsage::default());
}
#[test]
fn valid_stream_pairs_content_tools_usage_and_terminal() {
let mut grammar = StreamGrammar::new();
let events = [
Event::Usage(TokenUsage {
prompt: 1,
completion: 2,
total: 3,
cached: 4,
reasoning: 5,
}),
text_delta("text", ContentKind::Text, "hel"),
text_delta("text", ContentKind::Text, "lo"),
text_final("text", ContentKind::Text, "hello"),
text_delta("thought", ContentKind::Thinking, "why"),
text_final("thought", ContentKind::Thinking, "why"),
Event::ToolCallStart {
id: id("call"),
name: name("search"),
},
Event::ToolCallArgumentsDelta {
id: id("call"),
delta: payload(b"{\"q\":\""),
},
Event::ToolCallArgumentsDelta {
id: id("call"),
delta: payload(b"reef\"}"),
},
Event::ToolCallFinal {
call: call("call", "search", br#"{"q":"reef"}"#),
extensions: extensions(),
},
done(),
];
for event in &events {
grammar.accept(event).unwrap();
}
grammar.finish().unwrap();
let reasons = [
CompletionReason::Unknown,
CompletionReason::Length,
CompletionReason::ToolCalls,
CompletionReason::ContentFilter,
];
assert_eq!(reasons.len(), 4);
let cloned_terminal = events[10].clone();
if let Event::Done {
finish_reason,
completion,
provider_data,
} = &cloned_terminal
{
assert_eq!(finish_reason, "stop");
assert_eq!(*completion, CompletionReason::Stop);
assert!(provider_data.is_empty());
} else {
panic!("fixture terminal changed");
}
if let Event::ContentFinal { extensions, .. } = &events[3] {
assert_eq!(extensions.signature(), "");
} else {
panic!("fixture final changed");
}
if let Event::ToolCallFinal { extensions, .. } = &events[9] {
assert_eq!(extensions.signature(), "");
} else {
panic!("fixture tool final changed");
}
}
#[test]
fn several_usage_increments_are_legal_before_terminal() {
let mut grammar = StreamGrammar::new();
let increments = [TokenUsage::new(1, 2), TokenUsage::new(3, 4)];
for increment in increments {
grammar.accept(&Event::Usage(increment)).unwrap();
}
grammar.accept(&done()).unwrap();
grammar.finish().unwrap();
}
#[test]
fn terminal_and_identity_failures_are_rejected() {
assert_eq!(
StreamGrammar::new().finish(),
Err(StreamError::MissingTerminal)
);
let mut grammar = StreamGrammar::new();
grammar.accept(&done()).unwrap();
assert_eq!(grammar.accept(&done()), Err(StreamError::EventAfterDone));
let mut grammar = StreamGrammar::new();
grammar
.accept(&text_delta("open", ContentKind::Text, "x"))
.unwrap();
assert_eq!(grammar.accept(&done()), Err(StreamError::UnfinishedItems));
grammar
.accept(&text_final("open", ContentKind::Text, "x"))
.unwrap();
grammar.accept(&done()).unwrap();
for event in [
text_delta("", ContentKind::Text, "x"),
text_final("", ContentKind::Text, ""),
Event::ToolCallStart {
id: id(""),
name: name("tool"),
},
Event::ToolCallArgumentsDelta {
id: id(""),
delta: payload(b"x"),
},
Event::ToolCallFinal {
call: call("", "tool", b""),
extensions: extensions(),
},
] {
assert_eq!(
StreamGrammar::new().accept(&event),
Err(StreamError::EmptyItemId)
);
}
assert_eq!(
StreamGrammar::new().accept(&Event::ToolCallStart {
id: id("call"),
name: name("")
}),
Err(StreamError::EmptyToolName),
);
let mut grammar = StreamGrammar::new();
grammar
.accept(&Event::ToolCallStart {
id: id("call"),
name: name("tool"),
})
.unwrap();
assert_eq!(
grammar.accept(&Event::ToolCallFinal {
call: call("call", "", b""),
extensions: extensions()
}),
Err(StreamError::EmptyToolName),
);
}
#[test]
fn content_lifecycle_rejects_kind_changes_mismatch_and_reuse() {
let mut grammar = StreamGrammar::new();
grammar
.accept(&text_delta("x", ContentKind::Text, "a"))
.unwrap();
assert_eq!(
grammar.accept(&text_delta("x", ContentKind::Thinking, "b")),
Err(StreamError::InvalidLifecycle("x".into()))
);
assert_eq!(
grammar.accept(&text_final("x", ContentKind::Text, "wrong")),
Err(StreamError::FinalPayloadMismatch("x".into()))
);
assert_eq!(
grammar.accept(&text_final("x", ContentKind::Thinking, "a")),
Err(StreamError::InvalidLifecycle("x".into()))
);
grammar
.accept(&text_final("x", ContentKind::Text, "a"))
.unwrap();
assert_eq!(
grammar.accept(&text_delta("x", ContentKind::Text, "again")),
Err(StreamError::DuplicateItemId("x".into()))
);
assert_eq!(
grammar.accept(&text_final("x", ContentKind::Text, "a")),
Err(StreamError::DuplicateItemId("x".into())),
"a closed identity is spent, whether it is reopened by a delta or by a final"
);
let mut grammar = StreamGrammar::new();
grammar
.accept(&Event::ToolCallStart {
id: id("tool"),
name: name("echo"),
})
.unwrap();
assert_eq!(
grammar.accept(&text_delta("tool", ContentKind::Text, "x")),
Err(StreamError::InvalidLifecycle("tool".into()))
);
assert_eq!(
grammar.accept(&text_final("tool", ContentKind::Text, "x")),
Err(StreamError::InvalidLifecycle("tool".into()))
);
}
#[test]
fn tool_lifecycle_rejects_mismatch_unopened_and_reuse() {
let mut grammar = StreamGrammar::new();
let delta = Event::ToolCallArgumentsDelta {
id: id("call"),
delta: payload(b"x"),
};
assert_eq!(
grammar.accept(&delta),
Err(StreamError::InvalidLifecycle("call".into()))
);
grammar
.accept(&text_delta("content", ContentKind::Text, "x"))
.unwrap();
assert_eq!(
grammar.accept(&Event::ToolCallArgumentsDelta {
id: id("content"),
delta: payload(b"x")
}),
Err(StreamError::InvalidLifecycle("content".into())),
);
assert_eq!(
grammar.accept(&Event::ToolCallFinal {
call: call("content", "tool", b"x"),
extensions: extensions()
}),
Err(StreamError::InvalidLifecycle("content".into())),
);
let mut grammar = StreamGrammar::new();
let start = || Event::ToolCallStart {
id: id("call"),
name: name("search"),
};
grammar.accept(&start()).unwrap();
assert_eq!(
grammar.accept(&start()),
Err(StreamError::DuplicateItemId("call".into()))
);
grammar
.accept(&Event::ToolCallArgumentsDelta {
id: id("call"),
delta: payload(b"arg"),
})
.unwrap();
for final_call in [
call("call", "other", b"arg"),
call("call", "search", b"wrong"),
] {
assert_eq!(
grammar.accept(&Event::ToolCallFinal {
call: final_call,
extensions: extensions()
}),
Err(StreamError::FinalPayloadMismatch("call".into())),
);
}
grammar
.accept(&Event::ToolCallFinal {
call: call("call", "search", b"arg"),
extensions: extensions(),
})
.unwrap();
assert_eq!(
grammar.accept(&start()),
Err(StreamError::DuplicateItemId("call".into()))
);
}
#[test]
fn a_final_with_no_preceding_delta_opens_and_closes_its_own_item() {
let mut grammar = StreamGrammar::new();
grammar
.accept(&text_final("answer", ContentKind::Text, "the whole answer"))
.unwrap();
assert_eq!(
grammar.accept(&text_final("answer", ContentKind::Text, "again")),
Err(StreamError::DuplicateItemId("answer".into()))
);
assert_eq!(
grammar.accept(&text_delta("answer", ContentKind::Text, "again")),
Err(StreamError::DuplicateItemId("answer".into()))
);
grammar
.accept(&Event::ToolCallStart {
id: id("announced"),
name: name("search"),
})
.unwrap();
assert_eq!(
grammar.accept(&Event::ToolCallFinal {
call: call("announced", "other", br#"{"q":"reef"}"#),
extensions: extensions()
}),
Err(StreamError::FinalPayloadMismatch("announced".into())),
"an empty accumulation still does not license renaming the tool"
);
grammar
.accept(&Event::ToolCallFinal {
call: call("announced", "search", br#"{"q":"reef"}"#),
extensions: extensions(),
})
.unwrap();
grammar
.accept(&Event::ToolCallFinal {
call: call("lone", "search", br#"{"q":"coral"}"#),
extensions: extensions(),
})
.unwrap();
assert_eq!(
grammar.accept(&Event::ToolCallStart {
id: id("lone"),
name: name("search")
}),
Err(StreamError::DuplicateItemId("lone".into()))
);
assert_eq!(
grammar.accept(&Event::ToolCallFinal {
call: call("lone", "search", br#"{"q":"coral"}"#),
extensions: extensions()
}),
Err(StreamError::DuplicateItemId("lone".into())),
"a spent call identity is spent for a repeated final too"
);
grammar.accept(&done()).unwrap();
grammar.finish().unwrap();
}
#[test]
fn stream_errors_have_stable_messages_and_error_surface() {
let errors = [
StreamError::EmptyItemId,
StreamError::EmptyToolName,
StreamError::DuplicateItemId("x".into()),
StreamError::InvalidLifecycle("x".into()),
StreamError::FinalPayloadMismatch("x".into()),
StreamError::UnfinishedItems,
StreamError::EventAfterDone,
StreamError::MissingTerminal,
];
let messages: Vec<_> = errors.iter().map(ToString::to_string).collect();
assert_eq!(messages[0], "model stream item id is empty");
assert_eq!(messages[1], "model stream tool name is empty");
assert_eq!(messages[2], "duplicate model stream item id: x");
assert_eq!(messages[3], "invalid model stream lifecycle for: x");
assert_eq!(messages[4], "model stream final payload mismatch for: x");
assert_eq!(messages[5], "model stream terminal has unfinished items");
assert_eq!(messages[6], "model stream event emitted after terminal");
assert_eq!(messages[7], "model stream ended without terminal");
assert!(errors.iter().all(|error| error.source().is_none()));
}
#[derive(Debug)]
struct ProviderError;
impl fmt::Display for ProviderError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str("provider")
}
}
impl Error for ProviderError {}
struct ProviderEvents(VecDeque<Result<Event, ProviderError>>);
impl futures_core::Stream for ProviderEvents {
type Item = Result<Event, ProviderError>;
fn poll_next(mut self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<Option<Self::Item>> {
Poll::Ready(self.0.pop_front())
}
}
struct MinimalClient;
impl Client for MinimalClient {
type Error = ProviderError;
type Stream = ProviderEvents;
fn info(&self) -> Info {
Info::new("model".into(), 8)
.with_tools(true)
.with_thinking(true)
}
fn generate(
&self,
request: Request,
) -> impl Future<Output = Result<Self::Stream, Self::Error>> + Send {
assert!(request.messages().is_empty());
ready(Ok(ProviderEvents(VecDeque::from([Ok(done())]))))
}
}
struct CountingClient {
generate_calls: AtomicUsize,
}
impl Client for CountingClient {
type Error = ProviderError;
type Stream = ProviderEvents;
fn info(&self) -> Info {
MinimalClient.info()
}
fn generate(
&self,
_: Request,
) -> impl Future<Output = Result<Self::Stream, Self::Error>> + Send {
self.generate_calls.fetch_add(1, Ordering::SeqCst);
ready(Ok(ProviderEvents(VecDeque::new())))
}
}
#[tokio::test]
async fn failed_request_construction_never_calls_provider_generate() {
let client = CountingClient {
generate_calls: AtomicUsize::new(0),
};
let request = RequestPlan::new().try_into_request(vec![result(
"orphan",
"tool",
ModelVisibility::Visible,
)]);
let error = match request {
Ok(request) => {
client.generate(request).await.unwrap();
panic!("invalid request unexpectedly reached provider")
}
Err(error) => error,
};
assert_eq!(
error,
RequestError::OrphanToolResult {
call_id: "orphan".into()
}
);
assert_eq!(client.generate_calls.load(Ordering::SeqCst), 0);
}
#[tokio::test]
async fn model_client_uses_native_rpitit_and_normalized_stream() {
let client = MinimalClient;
let info = client.info();
assert_eq!(info.id(), "model");
assert_eq!(info.context_window(), 8);
assert!(info.supports_tools() && !info.supports_vision() && info.supports_thinking());
assert!(info.extensions().is_empty());
let mut events = client
.generate(RequestPlan::new().try_into_request(Vec::new()).unwrap())
.await
.unwrap();
let waker = Waker::noop();
let mut context = Context::from_waker(waker);
let event = Pin::new(&mut events).poll_next(&mut context);
assert!(matches!(event, Poll::Ready(Some(Ok(Event::Done { .. })))));
assert!(matches!(
Pin::new(&mut events).poll_next(&mut context),
Poll::Ready(None)
));
}
#[test]
fn capability_growth_travels_through_the_opaque_extension_channel() {
fn envelope(namespace: &str, kind: &str, data: &[u8]) -> Envelope {
Envelope::try_new(namespace.to_owned(), kind.to_owned(), payload(data))
.expect("test envelopes are valid")
}
let info = Info::new("provider-model".into(), 200_000)
.with_vision(true)
.with_extension(envelope("example.compat", "matrix", br#"{"format":"a"}"#))
.with_extensions([
envelope("example.compat", "pricing", br#"{"tier":"flat"}"#),
envelope("other.vendor", "matrix", br#"{"format":"b"}"#),
]);
assert_eq!(info.id(), "provider-model");
assert_eq!(info.context_window(), 200_000);
assert!(info.supports_vision());
assert!(!info.supports_tools() && !info.supports_thinking());
assert_eq!(
info.extensions()
.iter()
.map(|extension| (extension.namespace(), extension.kind()))
.collect::<Vec<_>>(),
[
("example.compat", "matrix"),
("example.compat", "pricing"),
("other.vendor", "matrix"),
]
);
assert_eq!(
info.extension("example.compat", "matrix")
.expect("the first fact is present")
.as_bytes(),
br#"{"format":"a"}"#
);
assert_eq!(
info.extension("other.vendor", "matrix")
.expect("a same-kind fact in another namespace is distinct")
.as_bytes(),
br#"{"format":"b"}"#
);
assert!(info.extension("example.compat", "absent").is_none());
assert!(info.extension("absent.namespace", "matrix").is_none());
let cloned = info.clone();
assert_eq!(cloned.extensions().len(), 3);
assert_eq!(info, cloned);
}
#[test]
fn model_info_equality_is_field_wise_and_orders_the_extension_list() {
fn envelope(kind: &str) -> Envelope {
Envelope::try_new("example.compat".to_owned(), kind.to_owned(), payload(b"{}"))
.expect("test envelopes are valid")
}
let base = || Info::new("example-model".into(), 200_000).with_tools(true);
assert_eq!(base(), base());
assert_ne!(
base(),
Info::new("other-model".into(), 200_000).with_tools(true)
);
assert_ne!(
base(),
Info::new("Example-Model".into(), 200_000).with_tools(true)
);
assert_ne!(
base(),
Info::new("example-model".into(), 8_192).with_tools(true)
);
assert_ne!(base(), base().with_tools(false));
assert_ne!(base(), base().with_vision(true));
assert_ne!(base(), base().with_thinking(true));
let listed =
|first: &str, second: &str| base().with_extensions([envelope(first), envelope(second)]);
assert_eq!(listed("matrix", "pricing"), listed("matrix", "pricing"));
assert_ne!(listed("matrix", "pricing"), listed("pricing", "matrix"));
assert_ne!(base(), base().with_extension(envelope("matrix")));
let spelled = |data: &[u8]| {
base().with_extension(
Envelope::try_new(
"example.compat".to_owned(),
"matrix".to_owned(),
payload(data),
)
.expect("test envelopes are valid"),
)
};
assert_ne!(spelled(br#"{"a":1}"#), spelled(br#"{ "a" : 1 }"#));
}
#[test]
fn client_tool_debug_names_the_tool_and_sizes_what_the_model_reads() {
let tool = ClientTool::new(name("search"), SECRET.into(), payload(SECRET.as_bytes()));
assert_redacted(&tool);
assert_eq!(
format!("{tool:?}"),
r#"ClientTool { name: Name("search"), description: <21 bytes>, input_schema: <21 bytes> }"#
);
}
#[test]
fn sampling_params_debug_counts_stop_sequences_and_prints_the_controls() {
let params = SamplingParams {
temperature: Some(0.5),
reasoning_effort: Some("high".into()),
max_output_tokens: Some(256),
parallel_tool_calls: true,
output_schema: Some(payload(SECRET.as_bytes())),
stop_sequences: vec![SECRET.into(), SECRET.into(), SECRET.into()],
tool_choice: Some(ToolChoice::Specific(name("search"))),
};
assert_redacted(¶ms);
assert_states(
¶ms,
&[
"temperature: Some(0.5)",
r#"reasoning_effort: Some("high")"#,
"max_output_tokens: Some(256)",
"parallel_tool_calls: true",
"output_schema: Some(<21 bytes>)",
"stop_sequences: <3 items>",
r#"tool_choice: Some(Specific(Name("search")))"#,
],
);
assert_states(
&SamplingParams::default(),
&["stop_sequences: <0 items>", "output_schema: None"],
);
}
#[test]
fn model_event_debug_keeps_the_lifecycle_and_sizes_the_content() {
let cases = [
Event::ContentDelta {
id: SECRET.into(),
kind: ContentKind::Text,
delta: SECRET.into(),
},
Event::ContentFinal {
id: "item-1".into(),
kind: ContentKind::Thinking,
content: SECRET.into(),
extensions: SegmentExtensions::new(SECRET.into(), None, None),
},
Event::ToolCallStart {
id: id("call-1"),
name: name("search"),
},
Event::ToolCallArgumentsDelta {
id: id("call-1"),
delta: payload(SECRET.as_bytes()),
},
Event::ToolCallFinal {
call: ToolCall::new(id("call-1"), name("search"), payload(SECRET.as_bytes())),
extensions: extensions(),
},
Event::Usage(TokenUsage::default()),
Event::Done {
finish_reason: "stop".into(),
completion: CompletionReason::Stop,
provider_data: Vec::new(),
},
];
assert_states(
&cases[0],
&["ContentDelta", "kind: Text", "delta: <21 bytes>"],
);
assert!(
format!("{:?}", cases[0]).contains(SECRET),
"an item id is Tier 1"
);
for event in &cases[1..] {
assert_redacted(event);
}
assert_states(
&cases[1],
&[
"ContentFinal",
"kind: Thinking",
"content: <21 bytes>",
"signature: <present>",
],
);
assert_states(&cases[2], &["ToolCallStart", r#"Id("call-1")"#]);
assert_states(&cases[3], &["ToolCallArgumentsDelta", "delta: <21 bytes>"]);
assert_states(&cases[4], &["ToolCallFinal", "arguments: <21 bytes>"]);
assert_states(&cases[5], &["Usage", "prompt: 0"]);
assert_states(&cases[6], &[r#"finish_reason: "stop""#, "completion: Stop"]);
}
#[test]
fn stream_grammar_debug_reports_its_position_not_the_stream() {
let mut grammar = StreamGrammar::new();
assert_eq!(
format!("{grammar:?}"),
"StreamGrammar { open: 0, seen: 0, done: false }"
);
grammar
.accept(&Event::ContentDelta {
id: "item-1".into(),
kind: ContentKind::Text,
delta: SECRET.into(),
})
.expect("a first delta opens an item");
assert_redacted(&grammar);
assert_eq!(
format!("{grammar:?}"),
"StreamGrammar { open: 1, seen: 1, done: false }"
);
}
#[test]
fn request_and_plan_debug_inherit_redaction_from_every_lane() {
let mut plan = RequestPlan::new();
plan.push_system_instruction(Part::text(SECRET.into()))
.push_tool(ClientTool::new(
name("search"),
SECRET.into(),
payload(b"{}"),
))
.push_ephemeral(Part::text(SECRET.into()));
plan.sampling_mut().stop_sequences = vec![SECRET.into()];
assert_redacted(&plan);
assert_states(&plan, &["RequestPlan", "stop_sequences: <1 items>"]);
let request = plan
.try_into_request(vec![Item::System(System::new(
"instruction".into(),
SECRET.into(),
ModelVisibility::Visible,
))])
.expect("a well-formed projection freezes");
assert_redacted(&request);
assert_states(&request, &["Request", "text: <21 bytes>"]);
}
#[test]
fn model_info_debug_prints_capabilities_and_redacts_the_extension_bytes() {
let info = Info::new("example-model".into(), 200_000)
.with_tools(true)
.with_extension(
Envelope::try_new(
"example.compat".into(),
"matrix".into(),
payload(format!(r#"{{"t":"{SECRET}"}}"#).as_bytes()),
)
.expect("fixture is valid JSON"),
);
assert_redacted(&info);
assert_states(
&info,
&[
r#"id: "example-model""#,
"context_window: 200000",
"supports_tools: true",
r#"namespace: "example.compat""#,
"data: <29 bytes>",
],
);
}