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
//! Model request, attempt, fallback and commit-fence events.
use serde::{Deserialize, Serialize};
use crate::identity::CorrelationToken;
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct RequestBegin {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub request_token: Option<CorrelationToken>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct RequestEnd {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub request_token: Option<CorrelationToken>,
pub outcome: RequestOutcome,
pub elapsed_ms: u64,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum RequestOutcome {
Completed,
Failed,
Cancelled,
Timeout,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct RouteSelected {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub request_token: Option<CorrelationToken>,
/// Ordinal of the selected candidate in the plan, not a display name or endpoint.
pub candidate_ordinal: u64,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct AttemptBegin {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub request_token: Option<CorrelationToken>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub attempt_token: Option<CorrelationToken>,
pub attempt_index: u64,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub binding_token: Option<CorrelationToken>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub native_model: Option<NativeModelId>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub upstream_protocol: Option<IngressProtocol>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct AttemptEnd {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub attempt_token: Option<CorrelationToken>,
pub outcome: AttemptOutcome,
pub commit: CommitState,
pub elapsed_ms: u64,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub http_status: Option<u16>,
pub reasoning_fields_removed: u64,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub http_protocol: Option<WireHttpProtocol>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub provider_error: Option<WireProviderError>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub provider_result: Option<WireModelResult>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub commits: Option<AttemptWireCommits>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub native_model: Option<NativeModelId>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub request_reasoning: Option<WireRequestReasoning>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub upstream_request_token: Option<CorrelationToken>,
}
/// Counts only; never records history, signatures or provider error bodies.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ReasoningCleanup {
pub request_token: Option<CorrelationToken>,
pub attempt_token: Option<CorrelationToken>,
pub attempt_index: u64,
pub binding_token: Option<CorrelationToken>,
pub ingress_protocol: super::IngressProtocol,
pub upstream_protocol: super::IngressProtocol,
pub reason: ReasoningCleanupReason,
pub fields_removed_so_far: u64,
pub cleaned_prefix_len: Option<u64>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ReasoningCleanupReason {
RequestProtocolProjection,
ContextBreakRetry,
SuccessfulPrefixReuse,
ResponseProtocolProjection,
}
/// Closed categories only: never serializes provider messages, payloads or field values.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ResponseFailure {
pub request_token: Option<CorrelationToken>,
pub attempt_index: u64,
pub stage: ResponseFailureStage,
pub reason: ResponseFailureReason,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub attempt_token: Option<CorrelationToken>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub field: Option<ResponseFailureField>,
/// One-based SSE event visited, including the event rejected by the decoder.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub frame_index: Option<u64>,
/// Bytes supplied to the decoder, an upper bound rather than a token offset.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub received_bytes: Option<u64>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ResponseFailureField {
Object,
Choices,
Delta,
Content,
ToolCalls,
ToolId,
ToolName,
ToolArguments,
FinishReason,
Usage,
SystemFingerprint,
ServiceTier,
Logprobs,
Model,
Id,
Type,
Index,
Role,
Output,
Status,
Unknown,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ResponseFailureStage {
NativeProjection,
Decode,
Render,
PrefixBuffer,
ProviderStream,
EndOfStream,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ResponseFailureReason {
ResourceLimit,
InvalidJson,
InvalidSse,
InvalidField,
InvalidLifecycle,
MissingTerminal,
DuplicateTerminal,
Unrepresentable,
NoSemanticOutput,
ProviderRejected,
OtherProtocol,
UnsupportedField,
UnsupportedValue,
MissingToolIdentity,
InvalidToolArguments,
ProviderStateNotPortable,
ToolIdBindingRequired,
ToolContinuationConflict,
Capability,
ContextProjection,
Serialization,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum AttemptOutcome {
Completed,
Failed,
Cancelled,
Timeout,
}
/// How far a request got before it ended. Distinguishes a pre-send failure from an
/// uncertain post-transport result and a semantically committed result.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum CommitState {
BeforeTransport,
TransportCommitted,
SemanticCommitted,
Unknown,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Fallback {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub request_token: Option<CorrelationToken>,
pub from_attempt_index: u64,
pub reason: FallbackReason,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub next_attempt_index: Option<u64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub next_attempt_token: Option<CorrelationToken>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub next_binding_token: Option<CorrelationToken>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum FallbackReason {
PolicyEligibleFailure,
CandidateExcluded,
ConnectorUnavailable,
RateLimited,
UpstreamFailure,
AuthenticationRejected,
InputRejected,
Timeout,
InvalidOutput,
OtherStableReason,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct SemanticCommit {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub attempt_token: Option<CorrelationToken>,
pub state: CommitState,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct RequestCancel {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub request_token: Option<CorrelationToken>,
pub phase: CommitState,
pub accepted: bool,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct RequestTimeout {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub request_token: Option<CorrelationToken>,
pub phase: CommitState,
}
/// Bounded stage timings inside request handling. Only stable kinds and durations.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ModelStage {
pub stage: ModelStageKind,
pub elapsed_ms: u64,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub protocol: Option<IngressProtocol>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ModelStageKind {
IngressProtocol,
Parse,
Externalize,
Prevalidate,
Plan,
RuntimeExclusion,
Connect,
Ttfb,
CommitFence,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum IngressProtocol {
OpenAiChat,
OpenAiResponses,
AnthropicMessages,
Unknown,
}
/// Stable reason a runtime candidate was excluded, never a free-form message.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ExclusionReason {
AuthUnavailable,
QuotaExhausted,
DisabledByUser,
UnsupportedProtocol,
UnavailableConnector,
Other,
}
/// Wire-shape facts and bounded model/control fields: never raw header values,
/// URLs, prompts, provider messages or response bodies.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct UpstreamWire {
pub request_token: Option<CorrelationToken>,
pub phase: UpstreamWirePhase,
pub bearer_present: bool,
pub api_key_present: bool,
pub authorization_bytes: u64,
pub body_bytes: Option<u64>,
pub http_status: Option<u16>,
pub content_type: WireContentType,
pub request_reasoning: Option<WireRequestReasoning>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub request_kind: Option<WireRequestKind>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub attempt_token: Option<CorrelationToken>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub attempt_index: Option<u64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub native_model: Option<NativeModelId>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub upstream_request_token: Option<CorrelationToken>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub http_protocol: Option<WireHttpProtocol>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub provider_error: Option<WireProviderError>,
/// Present only for a verified managed CPA loopback target. Missing transport
/// evidence is Unknown; the logical attempt is never assumed to be one send.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub cpa_execution: Option<CpaExecution>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "status", rename_all = "snake_case", deny_unknown_fields)]
pub enum CpaExecution {
Unknown,
Known {
inference_attempts: u8,
unauthorized_responses: u8,
auth_recovery_attempts: u8,
auth_recovery_successes: u8,
},
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct WireRequestReasoning {
pub responses_effort: Option<WireReasoningEffort>,
pub chat_effort: Option<WireReasoningEffort>,
pub messages_effort: Option<WireReasoningEffort>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub messages_thinking: Option<WireThinkingType>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub messages_budget_tokens: Option<u64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub enable_thinking: Option<bool>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub thinking_enabled: Option<bool>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum WireReasoningEffort {
None,
Minimal,
Low,
Medium,
High,
Xhigh,
Max,
Ultra,
Other,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum UpstreamWirePhase {
Request,
Response,
Failure,
Completed,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum WireRequestKind {
ModelInference,
DecisionService,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum WireHttpProtocol {
Http1,
Http2,
}
/// The observed model terminal is independent of successful HTTP transport.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum WireModelResult {
Complete,
Failed,
Incomplete,
Unknown,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum WireThinkingType {
Enabled,
Disabled,
Adaptive,
Other,
}
/// Closed attribution only. Provider error text and arbitrary codes never enter logs.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum WireProviderError {
ThinkingBudgetRejected,
AuthenticationRejected,
RateLimited,
EndpointRejected,
InputRejected,
UpstreamUnavailable,
InvalidOutput,
Timeout,
Cancelled,
Unknown,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct AttemptWireCommits {
pub upstream_request: WireCommitState,
pub downstream_headers: WireCommitState,
/// Any response body byte, including a failure event, closes transparent replay.
pub downstream_body: WireCommitState,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum WireCommitState {
Clear,
Committed,
Poisoned,
}
/// Only a native identifier from the selected encoder may construct this field.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[serde(transparent)]
pub struct NativeModelId(String);
impl NativeModelId {
pub fn new(value: &str) -> Option<Self> {
(!value.is_empty()
&& value.len() <= 256
&& !value.contains("://")
&& value.bytes().all(|byte| {
byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_' | b'.' | b':' | b'/')
}))
.then(|| Self(value.to_owned()))
}
}
impl<'de> Deserialize<'de> for NativeModelId {
fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
struct Identifier;
impl<'de> serde::de::Visitor<'de> for Identifier {
type Value = NativeModelId;
fn expecting(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str("a bounded native model identifier")
}
fn visit_str<E: serde::de::Error>(self, value: &str) -> Result<Self::Value, E> {
NativeModelId::new(value)
.ok_or_else(|| E::custom("invalid native model identifier"))
}
}
deserializer.deserialize_str(Identifier)
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum WireContentType {
Json,
EventStream,
Html,
Other,
Missing,
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn historical_wire_and_attempt_records_keep_missing_facts_unknown() {
let old_wire = serde_json::json!({"request_token":null,"phase":"response",
"bearer_present":false,"api_key_present":false,"authorization_bytes":0,
"body_bytes":null,"http_status":400,"content_type":"json","request_reasoning":null});
let wire: UpstreamWire = serde_json::from_value(old_wire).unwrap();
assert!(wire.native_model.is_none() && wire.provider_error.is_none());
assert!(wire.attempt_index.is_none() && wire.http_protocol.is_none());
assert!(wire.cpa_execution.is_none());
let old_attempt = serde_json::json!({"attempt_token":null,"outcome":"failed",
"commit":"unknown","elapsed_ms":1,"http_status":400,"reasoning_fields_removed":0});
let attempt: AttemptEnd = serde_json::from_value(old_attempt).unwrap();
assert!(attempt.commits.is_none() && attempt.http_protocol.is_none());
let mut encoded = serde_json::to_value(wire).unwrap();
encoded["provider_error"] = "provider-secret-marker".into();
assert!(serde_json::from_value::<UpstreamWire>(encoded).is_err());
}
#[test]
fn native_model_field_rejects_content_urls_and_oversized_identifiers() {
for value in [
"",
"prompt with spaces",
"https://credential.invalid",
"model\nsecret",
&"x".repeat(257),
] {
assert!(NativeModelId::new(value).is_none());
assert!(serde_json::from_value::<NativeModelId>(serde_json::json!(value)).is_err());
}
assert_eq!(
serde_json::to_value(NativeModelId::new("provider/qwen3.6-flash:revision").unwrap())
.unwrap(),
"provider/qwen3.6-flash:revision"
);
}
}