Make Codex and Claude Code subscriptions go further: a local model router that gives routine agent work to economical models and keeps your strongest model for the hard parts.
Rust ai-agentsai-gatewayclaude-codecodexcoding-agentcost-optimizationdeepseekllm-gatewayllm-routerlocal-firstmodel-routingrusttask-routingtauri
//! Stateful native response decoding and client protocol rendering.
mod body_buffer;
mod client_stream;
mod completion;
mod decoder;
mod messages;
mod native_passthrough;
mod native_passthrough_sse;
mod protocols;
mod render;
mod responses_lifecycle;
mod search;
mod wire;
#[cfg(test)]
#[path = "native_passthrough_tests.rs"]
mod native_passthrough_tests;
#[cfg(test)]
mod native_reasoning_tests;
#[cfg(test)]
mod service_tier_tests;
#[cfg(test)]
mod size_tests;
#[cfg(test)]
pub(super) fn test_tool_projection() -> super::continuation::ToolIdProjection {
// Production installs the process key before requests. Golden response tests must supply
// their own request-bound projection so parallel runtime tests cannot change their result.
super::continuation::ToolIdProjection::new(IngressProtocol::Responses)
}
pub use decoder::{DecodedNativeResponse, NativeResponseDecoder, ResponseDecodeStatus};
pub(crate) use native_passthrough::{NativeResponseProjector, NativeTerminalOutcome};
pub use render::{ClientResponseRenderer, RenderedClientResponse, RenderedSseEvent};
use std::collections::{BTreeMap, VecDeque};
use serde_json::{Map, Value};
use crate::server::core_runtime::model_ir::{
ExactProviderPathV1, FinishReason, ModelError, ModelEvent, ModelIrError, ModelResponseIRV1,
ModelStreamEventV1, ModelUsage, MutableResponseBlock, OpaqueProviderState, ResponseAccumulator,
ResponseBlockKind, ResponseItemStatus, ToolKindV1,
};
use crate::server::core_runtime::profiles::NativeProviderStateEmission;
use crate::server::request_plan::IngressProtocol;
use super::ProtocolAdapterError;
/// Responses labels its ordinary assistant answer with `final_answer`. Messages and Chat
/// Completions have only that assistant-output channel, so the label is losslessly implicit in
/// those protocols. Every other named phase remains Responses-only and must fail closed.
fn client_can_represent_message_phase(protocol: IngressProtocol, phase: Option<&str>) -> bool {
phase.is_none() || protocol == IngressProtocol::Responses || phase == Some("final_answer")
}
struct ResponsesTerminalProjection {
event: &'static str,
status: &'static str,
incomplete_details: Value,
}
fn responses_terminal(
reason: &FinishReason,
) -> Result<ResponsesTerminalProjection, ProtocolAdapterError> {
let terminal = match reason {
FinishReason::Stop | FinishReason::ToolCall => ResponsesTerminalProjection {
event: "response.completed",
status: "completed",
incomplete_details: Value::Null,
},
FinishReason::Length => ResponsesTerminalProjection {
event: "response.incomplete",
status: "incomplete",
incomplete_details: serde_json::json!({"reason":"max_output_tokens"}),
},
FinishReason::Refusal => ResponsesTerminalProjection {
event: "response.incomplete",
status: "incomplete",
incomplete_details: serde_json::json!({"reason":"content_filter"}),
},
FinishReason::Cancelled | FinishReason::Other(_) => {
return Err(ProtocolAdapterError::ClientUnrepresentable(
"Responses has no exact terminal projection for the finish reason".into(),
));
}
};
Ok(terminal)
}
#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
enum NativeBlockKind {
Search,
Text,
Reasoning,
Refusal,
Tool,
}
#[derive(Clone, Debug)]
struct DecoderCore {
owner: ExactProviderPathV1,
tool_id_projection: Option<super::continuation::ToolIdProjection>,
provider_state_emission: NativeProviderStateEmission,
accumulator: ResponseAccumulator,
native_blocks: BTreeMap<(NativeBlockKind, u32), u32>,
native_item_ids: BTreeMap<u32, String>,
native_item_id_values: std::collections::BTreeSet<String>,
responses_encrypted_fallback: BTreeMap<u32, Value>,
responses_encrypted_final: BTreeMap<u32, Option<Value>>,
responses_encrypted_buffered_bytes: usize,
native_message_phases: BTreeMap<u32, String>,
search_ids: std::collections::BTreeSet<String>,
next_block: u32,
next_sequence: u64,
semantic_bytes: usize,
retention: body_buffer::Retention,
}
impl DecoderCore {
fn new(
owner: ExactProviderPathV1,
provider_state_emission: NativeProviderStateEmission,
tool_id_projection: Option<super::continuation::ToolIdProjection>,
) -> Self {
Self {
owner,
tool_id_projection,
provider_state_emission,
accumulator: ResponseAccumulator::default(),
native_blocks: BTreeMap::new(),
native_item_ids: BTreeMap::new(),
native_item_id_values: std::collections::BTreeSet::new(),
responses_encrypted_fallback: BTreeMap::new(),
responses_encrypted_final: BTreeMap::new(),
responses_encrypted_buffered_bytes: 0,
native_message_phases: BTreeMap::new(),
search_ids: std::collections::BTreeSet::new(),
next_block: 0,
next_sequence: 0,
semantic_bytes: 0,
retention: body_buffer::Retention::new(body_buffer::standalone_budget()),
}
}
fn block_index(
&mut self,
kind: NativeBlockKind,
native_index: u32,
) -> Result<(u32, bool), ProtocolAdapterError> {
let conflict = if kind == NativeBlockKind::Search {
[
NativeBlockKind::Text,
NativeBlockKind::Reasoning,
NativeBlockKind::Refusal,
NativeBlockKind::Tool,
]
.iter()
.any(|previous| self.native_blocks.contains_key(&(*previous, native_index)))
} else {
self.native_blocks
.contains_key(&(NativeBlockKind::Search, native_index))
};
if conflict {
return Err(ModelIrError::InvalidResponseLifecycle(
"search output index reused by another item kind".into(),
)
.into());
}
if let Some(index) = self.native_blocks.get(&(kind, native_index)) {
return Ok((*index, false));
}
let index = self.next_block;
self.retention.add(256)?;
self.next_block = self.next_block.checked_add(1).ok_or_else(|| {
ModelIrError::InvalidResponseLifecycle("content block index overflow".into())
})?;
self.native_blocks.insert((kind, native_index), index);
Ok((index, true))
}
fn emit(
&mut self,
event: ModelEvent,
output: &mut VecDeque<ModelStreamEventV1>,
) -> Result<(), ProtocolAdapterError> {
self.charge_semantics(&event)?;
self.apply(&event)?;
let sequence = self.next_sequence;
self.next_sequence = self.next_sequence.checked_add(1).ok_or_else(|| {
ModelIrError::InvalidResponseLifecycle("event sequence overflow".into())
})?;
output.push_back(ModelStreamEventV1::new(sequence, event));
Ok(())
}
fn register_native_item_id(
&mut self,
native_index: u32,
item_id: &str,
) -> Result<(), ProtocolAdapterError> {
if item_id.is_empty()
|| item_id.chars().any(char::is_control)
|| self.native_item_ids.contains_key(&native_index)
|| !self.native_item_id_values.insert(item_id.into())
{
return Err(ModelIrError::InvalidField("response output item id").into());
}
self.retention
.add(item_id.len().saturating_mul(2).saturating_add(128))?;
self.native_item_ids.insert(native_index, item_id.into());
Ok(())
}
fn validate_native_item_id(
&self,
native_index: u32,
item_id: &str,
) -> Result<(), ProtocolAdapterError> {
if self.native_item_ids.get(&native_index).map(String::as_str) == Some(item_id) {
Ok(())
} else {
Err(ModelIrError::InvalidResponseLifecycle(
"Responses event item ID changed during the stream".into(),
)
.into())
}
}
fn observe_responses_encrypted_fallback(
&mut self,
native_index: u32,
value: Value,
) -> Result<(), ProtocolAdapterError> {
if !self.native_item_ids.contains_key(&native_index)
|| self.responses_encrypted_final.contains_key(&native_index)
|| self
.responses_encrypted_fallback
.contains_key(&native_index)
{
return Err(ModelIrError::InvalidResponseLifecycle(
"invalid Responses encrypted reasoning fallback".into(),
)
.into());
}
let bytes = serde_json::to_vec(&value)
.map_err(|error| ModelIrError::InvalidJson(error.to_string()))?
.len();
self.retention.add(bytes)?;
self.responses_encrypted_buffered_bytes = self
.responses_encrypted_buffered_bytes
.checked_add(bytes)
.ok_or(ModelIrError::BufferLimit(usize::MAX))?;
self.responses_encrypted_fallback
.insert(native_index, value);
Ok(())
}
fn finalize_responses_encrypted_content(
&mut self,
native_index: u32,
authoritative: Option<&Value>,
final_snapshot: bool,
output: &mut VecDeque<ModelStreamEventV1>,
) -> Result<(), ProtocolAdapterError> {
if let Some(established) = self.responses_encrypted_final.get(&native_index) {
if authoritative.is_some() && established.as_ref() != authoritative {
return Err(ModelIrError::InvalidResponseLifecycle(
"Responses final encrypted reasoning state disagrees with output_item.done"
.into(),
)
.into());
}
return Ok(());
}
let fallback = self.responses_encrypted_fallback.remove(&native_index);
if let Some(value) = fallback.as_ref() {
self.responses_encrypted_buffered_bytes =
self.responses_encrypted_buffered_bytes.saturating_sub(
serde_json::to_vec(value)
.map_err(|error| ModelIrError::InvalidJson(error.to_string()))?
.len(),
);
}
let selected = authoritative.cloned().or(fallback);
if let Some(value) = selected.as_ref() {
self.provider_state(
IngressProtocol::Responses,
"encrypted_content",
value.clone(),
Some(native_index),
output,
)?;
}
self.responses_encrypted_final
.insert(native_index, selected);
if !final_snapshot && !self.native_item_ids.contains_key(&native_index) {
return Err(ModelIrError::InvalidResponseLifecycle(
"Responses encrypted reasoning state lacks an item identity".into(),
)
.into());
}
Ok(())
}
fn native_item_id(&self, native_index: u32) -> Option<String> {
self.native_item_ids.get(&native_index).cloned()
}
fn observe_message_phase(
&mut self,
native_index: u32,
phase: Option<&str>,
complete_item: bool,
) -> Result<(), ProtocolAdapterError> {
let Some(phase) = phase else {
if complete_item && self.native_message_phases.contains_key(&native_index) {
return Err(ModelIrError::InvalidResponseLifecycle(
"Responses completed message omitted its established phase".into(),
)
.into());
}
return Ok(());
};
if phase.is_empty() || phase.chars().any(char::is_control) {
return Err(ModelIrError::InvalidField("response output message phase").into());
}
if let Some(current) = self.native_message_phases.get(&native_index) {
if current == phase {
return Ok(());
}
return Err(ModelIrError::InvalidResponseLifecycle(
"Responses message phase changed during the stream".into(),
)
.into());
}
if self
.native_blocks
.contains_key(&(NativeBlockKind::Text, native_index))
|| self
.native_blocks
.contains_key(&(NativeBlockKind::Refusal, native_index))
{
return Err(ModelIrError::InvalidResponseLifecycle(
"Responses message phase arrived after message content".into(),
)
.into());
}
self.retention.add(phase.len())?;
self.semantic_bytes = self
.semantic_bytes
.checked_add(phase.len())
.ok_or(ModelIrError::BufferLimit(usize::MAX))?;
self.native_message_phases
.insert(native_index, phase.to_owned());
Ok(())
}
fn native_message_phase(&self, native_index: u32) -> Option<String> {
self.native_message_phases.get(&native_index).cloned()
}
fn charge_semantics(&mut self, event: &ModelEvent) -> Result<(), ProtocolAdapterError> {
let added = match event {
ModelEvent::ResponsesMetadata { metadata } => serde_json::to_vec(metadata)
.map_err(|error| ModelIrError::InvalidJson(error.to_string()))?
.len(),
ModelEvent::TextAnnotation { annotation, .. } => serde_json::to_vec(annotation)
.map_err(|error| ModelIrError::InvalidJson(error.to_string()))?
.len(),
ModelEvent::TextFinished { .. }
| ModelEvent::ReasoningFinished { .. }
| ModelEvent::RefusalFinished { .. } => 0,
ModelEvent::WebSearch {
item, native_id, ..
} => serde_json::to_vec(item)
.map_err(|error| ModelIrError::InvalidJson(error.to_string()))?
.len()
.saturating_add(native_id.len()),
ModelEvent::ResponseStarted {
response_id,
provider_model,
} => response_id.len().saturating_add(provider_model.len()),
ModelEvent::TextDelta { text, .. }
| ModelEvent::ReasoningDelta { text, .. }
| ModelEvent::RefusalDelta { text, .. }
| ModelEvent::ToolArgumentsDelta { delta: text, .. } => text.len(),
ModelEvent::ToolCallStarted {
logical_id,
native_id,
namespace,
name,
..
} => logical_id
.len()
.saturating_add(native_id.len())
.saturating_add(namespace.as_ref().map_or(0, String::len))
.saturating_add(name.len()),
ModelEvent::ProviderState { state } => serde_json::to_vec(&state.value)
.map_err(|error| ModelIrError::InvalidJson(error.to_string()))?
.len()
.saturating_add(state.kind.len()),
ModelEvent::ResponseFailed { error } => error
.code
.as_ref()
.map_or(0, String::len)
.saturating_add(error.message.as_ref().map_or(0, String::len)),
ModelEvent::ContentBlockStarted { .. }
| ModelEvent::ToolCallFinished { .. }
| ModelEvent::UsageUpdated { .. }
| ModelEvent::FinishReason { .. }
| ModelEvent::ResponseCompleted { .. } => 0,
};
let next = self
.semantic_bytes
.checked_add(added)
.ok_or(ModelIrError::BufferLimit(usize::MAX))?;
self.retention.add(added)?;
self.semantic_bytes = next;
Ok(())
}
fn apply(&mut self, event: &ModelEvent) -> Result<(), ProtocolAdapterError> {
if self.accumulator.terminal {
return Err(ModelIrError::DuplicateTerminalEvent.into());
}
match event {
ModelEvent::ResponsesMetadata { metadata } => {
self.accumulator.responses_metadata.extend(metadata.clone())
}
ModelEvent::TextAnnotation {
index,
annotation_index,
annotation,
} => {
if !matches!(
self.accumulator.blocks.get(index),
Some(MutableResponseBlock::Text(_))
) || self.accumulator.finished_text.contains(index)
|| annotation.start_index > annotation.end_index
{
return Err(invalid_block(*index, "citation"));
}
let annotations = self.accumulator.annotations.entry(*index).or_default();
if *annotation_index as usize != annotations.len() {
return Err(invalid_block(*index, "citation index"));
}
annotations.push(annotation.clone());
}
ModelEvent::TextFinished {
index,
text,
annotations,
status,
} => {
if !matches!(self.accumulator.blocks.get(index), Some(MutableResponseBlock::Text(current)) if current == text)
|| !self.accumulator.finished_text.insert(*index)
|| annotations
.iter()
.any(|annotation| annotation.start_index > annotation.end_index)
{
return Err(invalid_block(*index, "text completion"));
}
self.bind_item_status(*index, *status)?;
}
ModelEvent::ReasoningFinished {
index,
text,
status,
} => {
if !matches!(
self.accumulator.blocks.get(index),
Some(MutableResponseBlock::Reasoning(current)) if current == text
) || !self.accumulator.finished_reasoning.insert(*index)
{
return Err(invalid_block(*index, "reasoning completion"));
}
self.bind_item_status(*index, *status)?;
}
ModelEvent::RefusalFinished {
index,
text,
status,
} => {
if !matches!(
self.accumulator.blocks.get(index),
Some(MutableResponseBlock::Refusal(current)) if current == text
) || !self.accumulator.finished_refusal.insert(*index)
{
return Err(invalid_block(*index, "refusal completion"));
}
self.bind_item_status(*index, *status)?;
}
ModelEvent::WebSearch {
index,
phase,
item,
native_id,
owner,
} => {
search::apply(
&mut self.accumulator,
*index,
*phase,
item,
native_id,
owner,
&self.owner,
)?;
}
ModelEvent::ResponseStarted {
response_id,
provider_model,
} => {
if self.accumulator.response_id.is_some() {
return Err(ModelIrError::InvalidResponseLifecycle(
"response started more than once".into(),
)
.into());
}
self.accumulator.response_id = Some(response_id.clone());
self.accumulator.provider_model = Some(provider_model.clone());
}
ModelEvent::ContentBlockStarted {
index,
block_kind,
item_id,
phase,
} => {
let value = match block_kind {
ResponseBlockKind::Text => MutableResponseBlock::Text(String::new()),
ResponseBlockKind::Reasoning => MutableResponseBlock::Reasoning(String::new()),
ResponseBlockKind::Refusal => MutableResponseBlock::Refusal(String::new()),
ResponseBlockKind::ToolCall => {
return Err(ModelIrError::InvalidResponseLifecycle(
"tool blocks require ToolCallStarted".into(),
)
.into());
}
};
if self.accumulator.blocks.insert(*index, value).is_some() {
return Err(ModelIrError::InvalidResponseLifecycle(format!(
"content block {index} started twice"
))
.into());
}
self.bind_item_id(*index, item_id)?;
match (block_kind, phase) {
(ResponseBlockKind::Text | ResponseBlockKind::Refusal, Some(phase)) => {
if self
.accumulator
.message_phases
.insert(*index, phase.clone())
.is_some()
{
return Err(invalid_block(*index, "message phase"));
}
}
(ResponseBlockKind::Reasoning | ResponseBlockKind::ToolCall, Some(_)) => {
return Err(invalid_block(*index, "message phase on non-message block"));
}
(_, None) => {}
}
}
ModelEvent::TextDelta { index, .. }
if self.accumulator.finished_text.contains(index) =>
{
return Err(invalid_block(*index, "text after completion"));
}
ModelEvent::TextDelta { index, text } => match self.accumulator.blocks.get_mut(index) {
Some(MutableResponseBlock::Text(output)) => output.push_str(text),
_ => return Err(invalid_block(*index, "text delta")),
},
ModelEvent::ReasoningDelta { index, text } => {
if self.accumulator.finished_reasoning.contains(index) {
return Err(invalid_block(*index, "reasoning after completion"));
}
match self.accumulator.blocks.get_mut(index) {
Some(MutableResponseBlock::Reasoning(output)) => output.push_str(text),
_ => return Err(invalid_block(*index, "reasoning delta")),
}
}
ModelEvent::RefusalDelta { index, text } => {
if self.accumulator.finished_refusal.contains(index) {
return Err(invalid_block(*index, "refusal after completion"));
}
match self.accumulator.blocks.get_mut(index) {
Some(MutableResponseBlock::Refusal(output)) => output.push_str(text),
_ => return Err(invalid_block(*index, "refusal delta")),
}
}
ModelEvent::ToolCallStarted {
index,
logical_id,
native_id,
tool_kind,
namespace,
name,
owner,
item_id,
} => {
if logical_id.is_empty()
|| native_id.is_empty()
|| name.is_empty()
|| owner.as_ref() != &self.owner
{
return Err(ModelIrError::MissingToolIdentity(logical_id.clone()).into());
}
let block = MutableResponseBlock::ToolCall {
logical_id: logical_id.clone(),
native_id: native_id.clone(),
tool_kind: *tool_kind,
namespace: namespace.clone(),
name: name.clone(),
owner: owner.clone(),
arguments: String::new(),
finished: false,
};
if self.accumulator.blocks.insert(*index, block).is_some() {
return Err(ModelIrError::InvalidResponseLifecycle(format!(
"tool block {index} started twice"
))
.into());
}
self.bind_item_id(*index, item_id)?;
}
ModelEvent::ToolArgumentsDelta {
index,
logical_id,
delta,
} => match self.accumulator.blocks.get_mut(index) {
Some(MutableResponseBlock::ToolCall {
logical_id: current,
arguments,
finished: false,
..
}) if current == logical_id => arguments.push_str(delta),
_ => return Err(invalid_block(*index, "tool argument delta")),
},
ModelEvent::ToolCallFinished {
index,
logical_id,
tool_kind,
namespace,
name,
arguments,
status,
} => {
match self.accumulator.blocks.get_mut(index) {
Some(MutableResponseBlock::ToolCall {
logical_id: current_id,
tool_kind: current_kind,
namespace: current_namespace,
name: current_name,
arguments: current_arguments,
finished,
..
}) if current_id == logical_id
&& current_kind == tool_kind
&& current_namespace == namespace
&& current_name == name
&& !*finished =>
{
let parsed =
canonical_tool_arguments(*tool_kind, current_arguments, logical_id)?;
if &parsed != arguments {
return Err(ModelIrError::InvalidResponseLifecycle(format!(
"tool call {logical_id} final arguments disagree with deltas"
))
.into());
}
*finished = true;
}
_ => return Err(invalid_block(*index, "tool completion")),
}
self.bind_item_status(*index, *status)?;
}
ModelEvent::ProviderState { state } => {
if self.provider_state_emission != NativeProviderStateEmission::Native {
return Err(ModelIrError::ProviderStateNotPortable.into());
}
self.accumulator.provider_state.push(state.as_ref().clone());
}
ModelEvent::UsageUpdated { usage } => self.accumulator.usage.merge_from(usage),
ModelEvent::FinishReason { reason } => {
if self
.accumulator
.finish_reason
.replace(reason.clone())
.is_some()
{
return Err(ModelIrError::InvalidResponseLifecycle(
"finish reason emitted twice".into(),
)
.into());
}
if reason == &FinishReason::Refusal
&& !self
.accumulator
.blocks
.values()
.any(|block| matches!(block, MutableResponseBlock::Refusal(_)))
{
for block in self.accumulator.blocks.values_mut() {
if let MutableResponseBlock::Text(text) = block {
*block = MutableResponseBlock::Refusal(std::mem::take(text));
}
}
}
}
ModelEvent::ResponseCompleted { output } => {
let mut expected = self.accumulator.clone();
expected.terminal = true;
let expected = expected.finish(self.owner.upstream_protocol)?.blocks;
if &expected != output {
return Err(ModelIrError::InvalidResponseLifecycle(
"response completion snapshot disagrees with canonical output".into(),
)
.into());
}
self.accumulator.terminal = true;
}
ModelEvent::ResponseFailed { error } => {
self.accumulator.error = Some(error.clone());
self.accumulator.terminal = true;
}
}
Ok(())
}
fn bind_item_id(
&mut self,
index: u32,
item_id: &Option<String>,
) -> Result<(), ProtocolAdapterError> {
let Some(item_id) = item_id else {
return Ok(());
};
if item_id.is_empty()
|| item_id.chars().any(char::is_control)
|| self
.accumulator
.item_ids
.values()
.any(|value| value == item_id)
|| self
.accumulator
.item_ids
.insert(index, item_id.clone())
.is_some()
{
return Err(ModelIrError::InvalidField("response output item id").into());
}
Ok(())
}
fn bind_item_status(
&mut self,
index: u32,
status: ResponseItemStatus,
) -> Result<(), ProtocolAdapterError> {
if self
.accumulator
.item_statuses
.insert(index, status)
.is_some()
{
return Err(invalid_block(index, "item status"));
}
Ok(())
}
fn validate_item_status(
&self,
index: u32,
status: ResponseItemStatus,
) -> Result<(), ProtocolAdapterError> {
if self.accumulator.item_statuses.get(&index) != Some(&status) {
return Err(invalid_block(index, "item status"));
}
Ok(())
}
fn start_response(
&mut self,
response_id: String,
provider_model: String,
output: &mut VecDeque<ModelStreamEventV1>,
) -> Result<(), ProtocolAdapterError> {
if let (Some(current_id), Some(current_model)) = (
self.accumulator.response_id.as_deref(),
self.accumulator.provider_model.as_deref(),
) {
if current_id != response_id || current_model != provider_model {
return Err(ModelIrError::InvalidResponseLifecycle(
"native response identity changed during the stream".into(),
)
.into());
}
} else {
self.emit(
ModelEvent::ResponseStarted {
response_id,
provider_model,
},
output,
)?;
}
Ok(())
}
fn text_delta(
&mut self,
native_index: u32,
text: String,
output: &mut VecDeque<ModelStreamEventV1>,
) -> Result<(), ProtocolAdapterError> {
let (index, fresh) = self.block_index(NativeBlockKind::Text, native_index)?;
if fresh {
let item_id = self.native_item_id(native_index);
let phase = self.native_message_phase(native_index);
self.emit(
ModelEvent::ContentBlockStarted {
index,
block_kind: ResponseBlockKind::Text,
item_id,
phase,
},
output,
)?;
}
if !text.is_empty() {
self.emit(ModelEvent::TextDelta { index, text }, output)?;
}
Ok(())
}
fn reasoning_delta(
&mut self,
native_index: u32,
text: String,
output: &mut VecDeque<ModelStreamEventV1>,
) -> Result<(), ProtocolAdapterError> {
let (index, fresh) = self.block_index(NativeBlockKind::Reasoning, native_index)?;
if fresh {
let item_id = self.native_item_id(native_index);
self.emit(
ModelEvent::ContentBlockStarted {
index,
block_kind: ResponseBlockKind::Reasoning,
item_id,
phase: None,
},
output,
)?;
}
if !text.is_empty() {
self.emit(ModelEvent::ReasoningDelta { index, text }, output)?;
}
Ok(())
}
fn refusal_delta(
&mut self,
native_index: u32,
text: String,
output: &mut VecDeque<ModelStreamEventV1>,
) -> Result<(), ProtocolAdapterError> {
let (index, fresh) = self.block_index(NativeBlockKind::Refusal, native_index)?;
if fresh {
let item_id = self.native_item_id(native_index);
let phase = self.native_message_phase(native_index);
self.emit(
ModelEvent::ContentBlockStarted {
index,
block_kind: ResponseBlockKind::Refusal,
item_id,
phase,
},
output,
)?;
}
if !text.is_empty() {
self.emit(ModelEvent::RefusalDelta { index, text }, output)?;
}
Ok(())
}
fn reconcile_reasoning(
&mut self,
native_index: u32,
expected: &str,
output: &mut VecDeque<ModelStreamEventV1>,
) -> Result<(u32, String), ProtocolAdapterError> {
let (index, fresh) = self.block_index(NativeBlockKind::Reasoning, native_index)?;
if fresh {
let item_id = self.native_item_id(native_index);
self.emit(
ModelEvent::ContentBlockStarted {
index,
block_kind: ResponseBlockKind::Reasoning,
item_id,
phase: None,
},
output,
)?;
if !expected.is_empty() {
self.emit(
ModelEvent::ReasoningDelta {
index,
text: expected.into(),
},
output,
)?;
}
}
let suffix = match self.accumulator.blocks.get(&index) {
Some(MutableResponseBlock::Reasoning(text)) => expected
.strip_prefix(text)
.filter(|suffix| !suffix.is_empty())
.map(str::to_owned),
_ => None,
};
if let Some(text) = suffix {
self.emit(ModelEvent::ReasoningDelta { index, text }, output)?;
}
let text = match self.accumulator.blocks.get(&index) {
Some(MutableResponseBlock::Reasoning(text)) if text == expected => text.clone(),
_ => {
return Err(invalid_block(
index,
"final reasoning disagrees with deltas",
));
}
};
Ok((index, text))
}
fn finish_reasoning_with_status(
&mut self,
native_index: u32,
expected: &str,
status: ResponseItemStatus,
output: &mut VecDeque<ModelStreamEventV1>,
) -> Result<(), ProtocolAdapterError> {
let (index, text) = self.reconcile_reasoning(native_index, expected, output)?;
if self.accumulator.finished_reasoning.contains(&index) {
return self.validate_item_status(index, status);
}
self.emit(
ModelEvent::ReasoningFinished {
index,
text,
status,
},
output,
)
}
fn reconcile_refusal(
&mut self,
native_index: u32,
expected: &str,
output: &mut VecDeque<ModelStreamEventV1>,
) -> Result<(u32, String), ProtocolAdapterError> {
let (index, fresh) = self.block_index(NativeBlockKind::Refusal, native_index)?;
if fresh {
let item_id = self.native_item_id(native_index);
let phase = self.native_message_phase(native_index);
self.emit(
ModelEvent::ContentBlockStarted {
index,
block_kind: ResponseBlockKind::Refusal,
item_id,
phase,
},
output,
)?;
if !expected.is_empty() {
self.emit(
ModelEvent::RefusalDelta {
index,
text: expected.into(),
},
output,
)?;
}
}
let suffix = match self.accumulator.blocks.get(&index) {
Some(MutableResponseBlock::Refusal(text)) => expected
.strip_prefix(text)
.filter(|suffix| !suffix.is_empty())
.map(str::to_owned),
_ => None,
};
if let Some(text) = suffix {
self.emit(ModelEvent::RefusalDelta { index, text }, output)?;
}
let text = match self.accumulator.blocks.get(&index) {
Some(MutableResponseBlock::Refusal(text)) if text == expected => text.clone(),
_ => return Err(invalid_block(index, "final refusal disagrees with deltas")),
};
Ok((index, text))
}
fn finish_refusal_with_status(
&mut self,
native_index: u32,
expected: &str,
status: ResponseItemStatus,
output: &mut VecDeque<ModelStreamEventV1>,
) -> Result<(), ProtocolAdapterError> {
let (index, text) = self.reconcile_refusal(native_index, expected, output)?;
if self.accumulator.finished_refusal.contains(&index) {
return self.validate_item_status(index, status);
}
self.emit(
ModelEvent::RefusalFinished {
index,
text,
status,
},
output,
)
}
fn has_refusal(&self) -> bool {
self.accumulator
.blocks
.values()
.any(|block| matches!(block, MutableResponseBlock::Refusal(_)))
}
fn start_tool(
&mut self,
native_index: u32,
native_id: String,
kind: ToolKindV1,
namespace: Option<String>,
name: String,
output: &mut VecDeque<ModelStreamEventV1>,
) -> Result<u32, ProtocolAdapterError> {
let (index, fresh) = self.block_index(NativeBlockKind::Tool, native_index)?;
if fresh {
if self.accumulator.blocks.values().any(|block| {
matches!(block, MutableResponseBlock::ToolCall { native_id: current, .. } if current == &native_id)
}) {
return Err(ModelIrError::MissingToolIdentity(native_id).into());
}
if self.accumulator.response_id.is_none() {
return Err(ModelIrError::InvalidResponseLifecycle(
"Tool call arrived before native response identity".into(),
)
.into());
}
let logical_id = if let Some(projection) = &self.tool_id_projection {
projection.project(&native_id, &self.owner)?
} else {
super::continuation::project_delivered_tool_id(&native_id, &self.owner)?
};
if self.accumulator.blocks.values().any(|block| {
matches!(block, MutableResponseBlock::ToolCall { logical_id: current, .. } if current == &logical_id)
}) {
return Err(ModelIrError::ToolContinuationConflict.into());
}
let item_id = self.native_item_id(native_index);
self.emit(
ModelEvent::ToolCallStarted {
index,
logical_id,
native_id: native_id.clone(),
tool_kind: kind,
namespace,
name,
owner: Box::new(self.owner.clone()),
item_id,
},
output,
)?;
} else {
match self.accumulator.blocks.get(&index) {
Some(MutableResponseBlock::ToolCall {
native_id: current_native_id,
tool_kind: current_kind,
namespace: current_namespace,
name: current_name,
..
}) if current_native_id == &native_id
&& current_kind == &kind
&& current_namespace == &namespace
&& current_name == &name => {}
_ => return Err(invalid_block(index, "tool identity")),
}
}
Ok(index)
}
// Native and canonical identity components stay explicit so delta events
// cannot accidentally reuse a partial tool identity.
#[allow(clippy::too_many_arguments)]
fn tool_delta(
&mut self,
native_index: u32,
native_id: String,
kind: ToolKindV1,
namespace: Option<String>,
name: String,
delta: String,
output: &mut VecDeque<ModelStreamEventV1>,
) -> Result<(), ProtocolAdapterError> {
let index = self.start_tool(native_index, native_id, kind, namespace, name, output)?;
let logical_id = tool_logical_id(&self.accumulator, index)?;
if !delta.is_empty() {
self.emit(
ModelEvent::ToolArgumentsDelta {
index,
logical_id,
delta,
},
output,
)?;
}
Ok(())
}
fn finish_tool(
&mut self,
native_index: u32,
native_id: String,
kind: ToolKindV1,
namespace: Option<String>,
name: String,
output: &mut VecDeque<ModelStreamEventV1>,
) -> Result<(), ProtocolAdapterError> {
self.finish_tool_with_status(
native_index,
native_id,
kind,
namespace,
name,
ResponseItemStatus::Completed,
output,
)
}
#[allow(clippy::too_many_arguments)]
fn finish_tool_with_status(
&mut self,
native_index: u32,
native_id: String,
kind: ToolKindV1,
namespace: Option<String>,
name: String,
status: ResponseItemStatus,
output: &mut VecDeque<ModelStreamEventV1>,
) -> Result<(), ProtocolAdapterError> {
let index = self.start_tool(
native_index,
native_id,
kind,
namespace.clone(),
name.clone(),
output,
)?;
let logical_id = tool_logical_id(&self.accumulator, index)?;
let (arguments, finished) = match self.accumulator.blocks.get(&index) {
Some(MutableResponseBlock::ToolCall {
arguments,
finished,
..
}) => (
canonical_tool_arguments(kind, arguments, &logical_id)?,
*finished,
),
_ => return Err(invalid_block(index, "tool completion")),
};
if finished {
return self.validate_item_status(index, status);
}
self.emit(
ModelEvent::ToolCallFinished {
index,
logical_id,
tool_kind: kind,
namespace,
name,
arguments,
status,
},
output,
)
}
// Completion validates the same complete identity tuple as start/delta.
#[allow(clippy::too_many_arguments)]
fn finish_tool_with_arguments(
&mut self,
native_index: u32,
native_id: String,
kind: ToolKindV1,
namespace: Option<String>,
name: String,
expected: &str,
output: &mut VecDeque<ModelStreamEventV1>,
) -> Result<(), ProtocolAdapterError> {
self.finish_tool_with_arguments_status(
native_index,
native_id,
kind,
namespace,
name,
expected,
ResponseItemStatus::Completed,
output,
)
}
#[allow(clippy::too_many_arguments)]
fn reconcile_tool_with_arguments(
&mut self,
native_index: u32,
native_id: String,
kind: ToolKindV1,
namespace: Option<String>,
name: String,
expected: &str,
output: &mut VecDeque<ModelStreamEventV1>,
) -> Result<(), ProtocolAdapterError> {
let index = self.start_tool(
native_index,
native_id.clone(),
kind,
namespace.clone(),
name.clone(),
output,
)?;
let current = match self.accumulator.blocks.get(&index) {
Some(MutableResponseBlock::ToolCall { arguments, .. }) => arguments.clone(),
_ => return Err(invalid_block(index, "tool completion")),
};
if let Some(suffix) = expected
.strip_prefix(¤t)
.filter(|suffix| !suffix.is_empty())
{
self.tool_delta(
native_index,
native_id.clone(),
kind,
namespace.clone(),
name.clone(),
suffix.into(),
output,
)?;
} else if current != expected {
return Err(ModelIrError::InvalidResponseLifecycle(
"native final tool arguments disagree with deltas".into(),
)
.into());
}
Ok(())
}
#[allow(clippy::too_many_arguments)]
fn finish_tool_with_arguments_status(
&mut self,
native_index: u32,
native_id: String,
kind: ToolKindV1,
namespace: Option<String>,
name: String,
expected: &str,
status: ResponseItemStatus,
output: &mut VecDeque<ModelStreamEventV1>,
) -> Result<(), ProtocolAdapterError> {
self.reconcile_tool_with_arguments(
native_index,
native_id.clone(),
kind,
namespace.clone(),
name.clone(),
expected,
output,
)?;
self.finish_tool_with_status(
native_index,
native_id,
kind,
namespace,
name,
status,
output,
)
}
fn provider_state(
&mut self,
protocol: IngressProtocol,
kind: impl Into<String>,
value: Value,
native_block_index: Option<u32>,
output: &mut VecDeque<ModelStreamEventV1>,
) -> Result<(), ProtocolAdapterError> {
if protocol != self.owner.upstream_protocol {
return Err(ModelIrError::ProviderStateNotPortable.into());
}
// `Never` is the compiled path's explicit instruction not to surface opaque provider
// state in Model IR. Known wire fields such as Responses `encrypted_content` may still
// be emitted by the provider and are safely consumed here rather than made portable.
if self.provider_state_emission == NativeProviderStateEmission::Never {
return Ok(());
}
if self.provider_state_emission != NativeProviderStateEmission::Native {
return Err(ModelIrError::ProviderStateNotPortable.into());
}
let kind = kind.into();
if let Some(native_index) = native_block_index
&& (protocol == IngressProtocol::Responses
|| matches!(
kind.as_str(),
"thinking_signature" | "thinking_signature_delta"
))
{
self.reasoning_delta(native_index, String::new(), output)?;
}
let block_index = native_block_index.and_then(|native_index| {
self.native_blocks
.get(&(NativeBlockKind::Reasoning, native_index))
.copied()
});
self.emit(
ModelEvent::ProviderState {
state: Box::new(OpaqueProviderState {
block_index,
kind,
value,
}),
},
output,
)
}
fn responses_metadata(
&mut self,
response: &Map<String, Value>,
output: &mut VecDeque<ModelStreamEventV1>,
) -> Result<(), ProtocolAdapterError> {
let metadata: BTreeMap<_, _> = response
.iter()
.filter(|(key, _)| {
!matches!(
key.as_str(),
"id" | "model" | "output" | "usage" | "status" | "error" | "incomplete_details"
)
})
.map(|(key, value)| (key.clone(), value.clone()))
.collect();
if !metadata.is_empty() {
self.emit(ModelEvent::ResponsesMetadata { metadata }, output)?;
}
Ok(())
}
fn usage(
&mut self,
usage: ModelUsage,
output: &mut VecDeque<ModelStreamEventV1>,
) -> Result<(), ProtocolAdapterError> {
if !usage.is_empty() {
self.emit(ModelEvent::UsageUpdated { usage }, output)?;
}
Ok(())
}
}
fn tool_logical_id(
accumulator: &ResponseAccumulator,
index: u32,
) -> Result<String, ProtocolAdapterError> {
match accumulator.blocks.get(&index) {
Some(MutableResponseBlock::ToolCall { logical_id, .. }) => Ok(logical_id.clone()),
_ => Err(invalid_block(index, "tool identity")),
}
}
fn canonical_tool_arguments(
kind: ToolKindV1,
arguments: &str,
logical_id: &str,
) -> Result<Value, ProtocolAdapterError> {
match kind {
ToolKindV1::Function => serde_json::from_str(arguments)
.map_err(|_| ModelIrError::InvalidToolArguments(logical_id.into()).into()),
ToolKindV1::Custom => Ok(Value::String(arguments.into())),
}
}
fn invalid_block(index: u32, operation: &str) -> ProtocolAdapterError {
ModelIrError::InvalidResponseLifecycle(format!(
"{operation} does not match content block {index}"
))
.into()
}
pub use client_stream::IncrementalClientSseRenderer;