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
use std::collections::BTreeMap;
use serde::{Deserialize, Serialize};
use thiserror::Error;
use crate::{AgentPlanId, CanonicalDigest, WorkspaceId};
use super::execution_attempt::{
AttemptFinishedFactV1, CacheStatusV1, CredentialLeaseOutcomeV1, ExecutionRequestOutcomeV1,
RuntimeHealthV1, RuntimeKeyScopeV1, RuntimeOperationOutcomeV1, RuntimeOperationV1,
SemanticCommitBoundaryV1, UsageProvenanceV1, UsageSourceV1,
};
use super::{
AttemptId, CorrelationProvenance, EventId, FactsCompleteness, FrozenValueFactsV1,
LogicalRequestId, ObservationStreamV1, SessionId, TrafficKind, TurnId, UsageFactsV1,
};
/// Authenticated storage formats whose released producers predate applicability.
/// This recognizes format evidence, never the absence of a decision marker.
pub fn is_pre_applicability_execution_digest(value: &str) -> bool {
matches!(
value,
"sha256:5aad4c450a2a296ec557b7a934bfbf70ad69a8e8fe9bc7539db46830a2940069"
| "sha256:de91d4f2333db66f0ec3f8b63ce192267dee0a56b65f34180b06996b232fb2c6"
| "sha256:80b4ff13af8abc79d7721fea42141300beade2acf1d2659983ceaafcdc6e4799"
| "sha256:4f0dbcc9f7862133e73e451f64d7a6d6e5de146d958ac8bf3a4d1acc885b6b1d"
)
}
/// Sole live Product execution-fact contract. Existing v1 rows are authenticated and read only
/// through `validate_persisted_contract`; they are never accepted by live ingestion.
pub const EXECUTION_FACT_SCHEMA_V2: &str = "hiroute.observation.product-execution-envelope/v2";
pub const EXECUTION_FACT_PORT_DIGEST_V2: &str =
"sha256:5f42929cdb812799e4e4a10885324debb21e6489bde5e935599de57b54b8ab23";
/// What the Gateway observed when it opened an agent turn. This is not proof
/// of human authorship or of a particular native compaction command.
#[derive(schemars::JsonSchema, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum AgentTurnOpeningCauseV1 {
UserMessage,
HistoryShortened,
HistoryRewrite,
NoComparableHistory,
Other,
}
/// Gateway profile digests are canonical except on its explicit degraded-observation path.
#[derive(schemars::JsonSchema, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(transparent)]
pub struct ObservedProfileDigestV1(String);
impl ObservedProfileDigestV1 {
pub fn parse(value: impl Into<String>) -> Result<Self, ExecutionFactError> {
let value = value.into();
if value == "unknown" || CanonicalDigest::parse(value.clone()).is_ok() {
Ok(Self(value))
} else {
Err(ExecutionFactError::InvalidFact)
}
}
pub fn as_str(&self) -> &str {
&self.0
}
pub(super) fn validate(&self) -> Result<(), ExecutionFactError> {
Self::parse(self.0.clone()).map(|_| ())
}
}
impl From<CanonicalDigest> for ObservedProfileDigestV1 {
fn from(value: CanonicalDigest) -> Self {
Self(value.as_str().to_owned())
}
}
#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum ExecutionFactChannelV1 {
ExecutionFact,
}
#[derive(schemars::JsonSchema, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
pub enum ExecutionProducerComponentV1 {
#[serde(rename = "gateway-execution")]
GatewayExecution,
}
#[derive(schemars::JsonSchema, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct ExecutionProducerV1 {
pub component: ExecutionProducerComponentV1,
pub revision: String,
pub stream: ObservationStreamV1,
}
#[derive(schemars::JsonSchema, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum SessionScopeV1 {
Conversation,
RequestScoped,
}
#[derive(schemars::JsonSchema, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct ExecutionCorrelationV1 {
pub workspace_id: WorkspaceId,
pub conversation_id: SessionId,
pub session_scope: SessionScopeV1,
pub correlation_provenance: CorrelationProvenance,
pub turn_id: TurnId,
pub request_id: LogicalRequestId,
}
#[derive(schemars::JsonSchema, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum SelectorSourceV1 {
TrustedModelAlias,
}
#[derive(schemars::JsonSchema, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum IngressProtocolV1 {
Responses,
ChatCompletions,
Messages,
/// Candidate-only value emitted when no materialized protocol profile was available.
Unknown,
}
/// Request-frozen authority/publication/Plan/grant identity repeated by every Gateway fact.
#[derive(schemars::JsonSchema, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct FrozenExecutionTrustV1 {
pub authority_id: String,
pub authority_epoch: u64,
pub served_model_id: String,
pub selector_source: SelectorSourceV1,
pub agent_plan_id: Option<AgentPlanId>,
pub route: crate::ModelRequestRouteV2,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub plan_display_name: Option<String>,
/// Exact decimal string carried by the Gateway envelope.
pub gateway_publication_revision: String,
pub gateway_publication_digest: CanonicalDigest,
pub grant_id: String,
pub grant_generation: u64,
pub ingress_protocol: IngressProtocolV1,
}
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct ExecutionLossWatermarkV1 {
pub first_sequence: u64,
pub last_sequence: u64,
pub reason: ExecutionLossReasonV1,
}
#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum ExecutionLossReasonV1 {
PublishContended,
QueueBytesExceeded,
QueueEventsExceeded,
EventTooLarge,
SinkFailed,
SinkPanicked,
SinkNack,
WorkerDisconnected,
Compacted,
}
impl ExecutionLossReasonV1 {
pub const fn as_str(self) -> &'static str {
match self {
Self::PublishContended => "publish_contended",
Self::QueueBytesExceeded => "queue_bytes_exceeded",
Self::QueueEventsExceeded => "queue_events_exceeded",
Self::EventTooLarge => "event_too_large",
Self::SinkFailed => "sink_failed",
Self::SinkPanicked => "sink_panicked",
Self::SinkNack => "sink_nack",
Self::WorkerDisconnected => "worker_disconnected",
Self::Compacted => "compacted",
}
}
}
#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum CompletenessDeltaV1 {
Partial,
Unknown,
}
#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct ExecutionFactEnvelopeV1 {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub pricing: Option<super::ExecutionPricingEvidenceV1>,
pub schema_version: String,
pub schema_digest: CanonicalDigest,
pub channel: ExecutionFactChannelV1,
pub producer: ExecutionProducerV1,
pub sequence: u64,
pub event_id: EventId,
pub correlation: ExecutionCorrelationV1,
#[serde(skip_serializing_if = "Option::is_none")]
pub attempt_id: Option<AttemptId>,
pub trust: FrozenExecutionTrustV1,
pub occurred_at_unix_nanos: u64,
pub fact: ExecutionFactV1,
#[serde(skip_serializing_if = "Option::is_none")]
pub loss_watermark: Option<ExecutionLossWatermarkV1>,
#[serde(skip_serializing_if = "Option::is_none")]
pub completeness_delta: Option<CompletenessDeltaV1>,
}
#[derive(schemars::JsonSchema, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum PlannedBranchV1 {
SmartSavingSimple,
SmartSavingComplex,
FreeFirstFreeOnly,
FreeFirstPrimaryFallback,
CustomExactOrder,
}
#[derive(schemars::JsonSchema, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum ComplexityDecisionSourceV1 {
Inherited,
ExternalClassifier,
UserPhrase,
BuiltinRules,
Unresolved,
}
#[derive(schemars::JsonSchema, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum ClassifierFallbackReasonV1 {
Timeout,
Unavailable,
RejectedInput,
InvalidOutput,
}
#[derive(schemars::JsonSchema, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
pub enum ComplexityReasonCodeV1 {
InheritedToolContinuation,
InheritedTaskRoot,
UserComplexPhrase,
DeepReasoning,
MultiFileScope,
MultiConstraint,
ImplementationAction,
FailureOrDiffStructure,
HumanLengthMedium,
HumanLengthLarge,
TaskContextUnresolved,
TaskLanguageFallback,
ClassifierAssessmentInvalid,
}
#[derive(schemars::JsonSchema, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum DecisionProtocolV1 {
SystemOneLegacy,
SystemOneC,
CustomExtensionV1,
LocalRules,
}
#[derive(schemars::JsonSchema, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct BranchDecisionV1 {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub extension_reason: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub decision_protocol: Option<DecisionProtocolV1>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub routing_observation: Option<crate::RoutingObservationV1>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub policy: Option<crate::BranchExecutionPolicyV1>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub competence_trigger: Option<crate::CompetenceProtectionV1>,
pub execution_group: crate::ExecutionGroupV1,
pub simple_probability: Option<serde_json::Number>,
pub simple_threshold_millis: Option<u16>,
pub selection_reason: crate::ModelGroupReasonV1,
pub strategy_id: String,
pub schema_version: String,
pub payload_digest: CanonicalDigest,
pub branch_id: String,
pub complexity_score: Option<u8>,
pub threshold: Option<u8>,
pub decision_source: ComplexityDecisionSourceV1,
pub reason_codes: Vec<ComplexityReasonCodeV1>,
pub matched_user_phrase_ids: Vec<String>,
pub fallback_used: bool,
pub classification_duration_micros: Option<u64>,
pub fallback_reason: Option<ClassifierFallbackReasonV1>,
}
impl BranchDecisionV1 {
pub(crate) fn validate(&self) -> Result<(), ExecutionFactError> {
if self.extension_reason.as_ref().is_some_and(|reason| {
reason.is_empty()
|| reason.chars().count() > 1024
|| self.decision_protocol != Some(DecisionProtocolV1::CustomExtensionV1)
}) {
return Err(ExecutionFactError::InvalidFact);
}
if self
.routing_observation
.as_ref()
.is_some_and(|o| !o.validate())
{
return Err(ExecutionFactError::InvalidFact);
}
if self.strategy_id.trim().is_empty()
|| self.schema_version.trim().is_empty()
|| CanonicalDigest::parse(self.payload_digest.as_str()).is_err()
|| self.branch_id.trim().is_empty()
|| self.branch_id.len() > 128
|| self.branch_id.chars().any(char::is_control)
|| self.complexity_score.is_some() != self.threshold.is_some()
|| self
.policy
.as_ref()
.is_some_and(|policy| !policy.validate())
|| self.simple_threshold_millis.is_some_and(|t| t > 1000)
|| self.simple_probability.as_ref().is_some_and(|p| {
p.as_f64()
.is_none_or(|p| !p.is_finite() || !(0.0..=1.0).contains(&p))
})
|| self.competence_trigger.as_ref().is_some_and(|upgrade| {
upgrade.segment_id.trim().is_empty()
|| upgrade.segment_id.len() > 256
|| upgrade.floor_millis > 1000
|| upgrade.score.as_f64().is_none_or(|score| {
!score.is_finite()
|| !(0.0..=1.0).contains(&score)
|| score >= f64::from(upgrade.floor_millis) / 1000.0
})
})
{
return Err(ExecutionFactError::InvalidFact);
}
let timed = self.classification_duration_micros.is_some();
let fallback_reason = self.fallback_reason.is_some();
let valid = match self.decision_source {
ComplexityDecisionSourceV1::ExternalClassifier => {
timed && self.complexity_score.is_none() && !self.fallback_used && !fallback_reason
}
ComplexityDecisionSourceV1::Inherited => {
if self.complexity_score.is_none() {
timed && !self.fallback_used && !fallback_reason
} else if timed {
self.fallback_used && fallback_reason
} else {
!fallback_reason
}
}
ComplexityDecisionSourceV1::UserPhrase
| ComplexityDecisionSourceV1::BuiltinRules
| ComplexityDecisionSourceV1::Unresolved => {
self.complexity_score.is_some()
&& if timed {
timed && self.fallback_used && fallback_reason
} else {
!timed && !fallback_reason
}
}
};
if valid {
Ok(())
} else {
Err(ExecutionFactError::InvalidFact)
}
}
}
#[derive(schemars::JsonSchema, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct GroupPlanV1 {
pub ordinal: u32,
pub group_id: String,
pub ranked_candidate_ids: Vec<String>,
}
#[derive(schemars::JsonSchema, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
pub enum LedgerReasonCodeV1 {
ContextHoldApplied,
ContextHoldInvalidated,
PreviousSuccessFallback,
SmartSavingSimple,
SmartSavingComplex,
FreeFirstNoClassification,
CustomNoClassification,
GroupExhaustedFallback,
ComplexNoDowngrade,
FreeOnlyBoundary,
CustomExactOrder,
}
#[derive(schemars::JsonSchema, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct ReasonLedgerEntryV1 {
pub ordinal: u32,
pub code: LedgerReasonCodeV1,
pub group_id: Option<String>,
}
#[derive(
schemars::JsonSchema, Clone, Copy, Debug, Default, Deserialize, Eq, PartialEq, Serialize,
)]
#[serde(rename_all = "snake_case")]
pub enum ToolKindRequirementV1 {
#[default]
Function,
Custom,
}
impl ToolKindRequirementV1 {
fn is_function(&self) -> bool {
*self == Self::Function
}
}
#[derive(schemars::JsonSchema, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
pub enum ToolChoiceRequirementV1 {
None,
Auto,
RequiredAny,
RequiredNamed {
// Released Product facts identify only functions. Keep their canonical bytes and
// authenticated digests; Custom must retain its explicit callable discriminator.
// Gateway's live DTO still requires tool_kind before the adapter reaches this codec.
#[serde(default, skip_serializing_if = "ToolKindRequirementV1::is_function")]
tool_kind: ToolKindRequirementV1,
name: String,
},
}
#[derive(schemars::JsonSchema, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct RequestCapabilityRequirementsV1 {
pub ingress_protocol: IngressProtocolV1,
pub text: bool,
pub initial_instructions: bool,
pub mid_conversation_instructions: bool,
pub image_url: bool,
pub image_base64: bool,
pub image_media_types: Vec<String>,
pub function_tools: bool,
pub strict_tools: bool,
pub tool_choice: ToolChoiceRequirementV1,
pub parallel_tools: bool,
pub tool_roundtrip: bool,
pub tool_result_text: bool,
pub tool_result_json: bool,
pub logical_tool_id_mapping: bool,
pub streaming: bool,
pub stream_text: bool,
pub stream_tool_arguments: bool,
pub stream_reasoning: bool,
pub stream_usage: bool,
pub provider_state: bool,
}
#[derive(schemars::JsonSchema, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum RequestedReasoningDispositionV1 {
Absent,
OverriddenByAgentPlan,
}
/// Typed carrier for the one intentionally provider-native reasoning field.
/// Stable route/candidate fields never use this representation.
#[derive(schemars::JsonSchema, Clone, Debug, Deserialize, PartialEq, Serialize)]
#[serde(
tag = "kind",
content = "value",
rename_all = "snake_case",
deny_unknown_fields
)]
pub enum NativeReasoningValueV1 {
Null,
Bool(bool),
Signed(i64),
Unsigned(u64),
Decimal(f64),
String(String),
Array(Vec<NativeReasoningValueV1>),
Object(BTreeMap<String, NativeReasoningValueV1>),
}
impl NativeReasoningValueV1 {
pub(super) fn validate(&self) -> Result<(), ExecutionFactError> {
match self {
Self::Decimal(value) if !value.is_finite() => Err(ExecutionFactError::InvalidFact),
Self::Array(values) => values.iter().try_for_each(Self::validate),
Self::Object(values) => values.values().try_for_each(Self::validate),
_ => Ok(()),
}
}
}
#[derive(schemars::JsonSchema, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum RouteDecisionOutcomeV1 {
Ready,
NoEligibleCandidates,
}
#[derive(schemars::JsonSchema, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
pub enum RouteDecisionOutcomeCodeV1 {
NoEligibleCandidate,
}
#[derive(schemars::JsonSchema, Clone, Debug, Deserialize, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct RouteDecisionFactV1 {
pub planner_version: String,
pub plan_id: Option<AgentPlanId>,
pub route: crate::ModelRequestRouteV2,
pub input_digest: CanonicalDigest,
pub policy_digest: CanonicalDigest,
pub output_digest: CanonicalDigest,
pub branch: PlannedBranchV1,
pub complexity: Option<BranchDecisionV1>,
pub groups: Vec<GroupPlanV1>,
pub reason_ledger: Vec<ReasonLedgerEntryV1>,
pub requirements: RequestCapabilityRequirementsV1,
pub requested_reasoning_disposition: RequestedReasoningDispositionV1,
pub requested_reasoning_value: Option<NativeReasoningValueV1>,
pub requested_max_output_tokens: Option<u64>,
pub stream: bool,
pub outcome: RouteDecisionOutcomeV1,
pub outcome_code: Option<RouteDecisionOutcomeCodeV1>,
pub max_attempts: u32,
}
#[derive(schemars::JsonSchema, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
pub enum CacheCostFactV1 {
None,
EligibleUnconfirmed,
Confirmed { projected_cost_micros: u64 },
}
#[derive(schemars::JsonSchema, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum CostClassV1 {
Free,
Subscription,
Paid,
Unknown,
}
#[derive(schemars::JsonSchema, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
pub enum ExclusionReasonCodeV1 {
ProtocolPathUnavailable,
VisionUnsupported,
ImageSourceUnsupported,
ToolInterfaceUnsupported,
ToolChoiceUnsupported,
ToolRoundtripUnsupported,
ReasoningProfileMismatch,
ContextLimitUnknown,
MaxOutputUnsupported,
StreamFeatureUnsupported,
OpaqueStateUnportable,
CostPolicyExcluded,
PaidBudgetQuoteUnavailable,
QualityAnchorUnavailable,
RatingUnknown,
RatingGuardExcluded,
StaticPlanExcluded,
DuplicateCandidate,
}
#[derive(schemars::JsonSchema, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
pub enum RankingReasonCodeV1 {
ContextModelHold,
PreviousSuccessFallback,
PublishedManualOrder,
QualityFirst,
LowestApiEquivalentCost,
ConfirmedCacheHold,
UnconfirmedAffinityTieBreak,
StableTieBreak,
}
#[derive(schemars::JsonSchema, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct CandidateDecisionFactV1 {
pub candidate_id: String,
pub stable_binding_id: String,
pub group_id: String,
pub declared_order: u32,
pub profile_digest: ObservedProfileDigestV1,
pub ingress_protocol: IngressProtocolV1,
pub upstream_protocol: IngressProtocolV1,
pub path_id: String,
pub provider_id: String,
pub endpoint_id: String,
pub entitlement_id: String,
pub connector_id: String,
pub connector_revision: String,
pub capability_id: String,
pub capability_revision: String,
pub model_configuration_id: String,
pub native_model: String,
pub adapter_revision: String,
pub serializer_revision: String,
pub decoder_revision: String,
pub target_serialized_bytes: u64,
pub eligible: bool,
pub exclusion_reason: Option<ExclusionReasonCodeV1>,
pub reasoning_profile_id: Option<String>,
pub overall_score_tenths: Option<i32>,
pub effective_cost_micros: Option<u64>,
pub api_equivalent_cost_micros: Option<u64>,
pub cost_class: CostClassV1,
/// Gateway emits null when the candidate profile was unavailable.
pub cache_cost: Option<CacheCostFactV1>,
pub cache_affinity: bool,
pub compute_scope_order: u32,
pub ranking_reasons: Vec<RankingReasonCodeV1>,
}
#[derive(schemars::JsonSchema, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum AgentTurnAttributionV1 {
Single,
Mixed,
Unknown,
}
#[derive(schemars::JsonSchema, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum AgentTurnStatusV1 {
Completed,
Failed,
Interrupted,
Unknown,
}
#[derive(schemars::JsonSchema, Clone, Debug, Deserialize, PartialEq, Serialize)]
#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
pub enum ExecutionFactV1 {
RouteDecision(Box<RouteDecisionFactV1>),
CandidateDecision(Box<CandidateDecisionFactV1>),
CredentialLease {
stable_binding_id: String,
credential_ref: String,
key_id: Option<String>,
credential_generation: Option<u64>,
excluded_key_count: u64,
outcome: CredentialLeaseOutcomeV1,
},
RuntimeState {
operation: RuntimeOperationV1,
key_scope: RuntimeKeyScopeV1,
stable_binding_id: String,
credential_ref: Option<String>,
key_id: Option<String>,
expected_generation: Option<u64>,
observed_generation: Option<u64>,
health: Option<RuntimeHealthV1>,
cooldown_remaining_millis: Option<u64>,
probe_lease_remaining_millis: Option<u64>,
transient_backoff_step: Option<u8>,
outcome: RuntimeOperationOutcomeV1,
},
AttemptStarted {
ordinal: u32,
candidate_id: String,
stable_binding_id: String,
profile_digest: ObservedProfileDigestV1,
credential_ref: String,
key_id: String,
provider_name: String,
request_model: String,
upstream_protocol: IngressProtocolV1,
model_configuration_id: String,
adapter_revision: String,
start_reason: String,
previous_attempt_id: Option<AttemptId>,
},
AttemptFinished(Box<AttemptFinishedFactV1>),
SemanticCommit {
ordinal: u32,
boundary: SemanticCommitBoundaryV1,
frame_id: String,
},
UsageAndCache {
ordinal: u32,
source: UsageSourceV1,
input_tokens: Option<u64>,
output_tokens: Option<u64>,
billable_tokens: Option<u64>,
cache_read_tokens: Option<u64>,
cache_write_tokens: Option<u64>,
reasoning_tokens: Option<u64>,
input_provenance: UsageProvenanceV1,
output_provenance: UsageProvenanceV1,
billable_provenance: UsageProvenanceV1,
cache_read_provenance: UsageProvenanceV1,
cache_write_provenance: UsageProvenanceV1,
reasoning_provenance: UsageProvenanceV1,
effective_cost_micros: Option<u64>,
cost_class: Option<CostClassV1>,
cache_status: CacheStatusV1,
},
RequestFinished {
outcome: ExecutionRequestOutcomeV1,
attempts_started: u32,
attempts_finished: u32,
accepted_attempt_ordinal: Option<u32>,
facts_completeness: FactsCompleteness,
},
AgentTurnFinished {
#[serde(default, skip_serializing_if = "Option::is_none")]
opening_cause: Option<AgentTurnOpeningCauseV1>,
#[serde(default, skip_serializing_if = "Option::is_none")]
branch_execution: Option<crate::BranchExecutionV1>,
agent_turn_id: String,
segment_id: String,
ordinal: u64,
plan_id: AgentPlanId,
plan_revision: u64,
selected_branch_id: String,
executed_branch_id: Option<String>,
model_configuration_id: Option<String>,
profile_digest: Option<ObservedProfileDigestV1>,
attribution: AgentTurnAttributionV1,
started_at_ms: u64,
finished_at_ms: u64,
status: AgentTurnStatusV1,
history_partial: bool,
first_request_id: Option<LogicalRequestId>,
last_request_id: Option<LogicalRequestId>,
},
BranchAssessmentRecorded {
segment_id: String,
plan_id: AgentPlanId,
plan_revision: u64,
model_configuration_id: String,
profile_digest: ObservedProfileDigestV1,
trigger_request_id: LogicalRequestId,
target_from_turn_id: TurnId,
target_through_turn_id: TurnId,
target_from_ordinal: u64,
target_through_ordinal: u64,
assessed_at_ms: u64,
score: f64,
partial: bool,
reason: Option<String>,
},
/// Product-owned immutable value input. Gateway mapping never aggregates into this event.
ValueSnapshot {
traffic_kind: TrafficKind,
usage: UsageFactsV1,
value: FrozenValueFactsV1,
},
}
#[derive(Clone, Copy, Debug, Error, Eq, PartialEq)]
pub enum ExecutionFactError {
#[error("execution fact schema or contract digest is unsupported")]
UnsupportedSchema,
#[error("execution fact envelope is invalid")]
InvalidEnvelope,
#[error("execution fact trust identity is invalid")]
InvalidTrustIdentity,
#[error("execution fact attempt scope is invalid")]
InvalidAttemptScope,
#[error("execution fact loss watermark is invalid")]
InvalidLossWatermark,
#[error("execution fact payload is invalid")]
InvalidFact,
}