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
//! Portable V2 observation scope and query contracts. Reader contexts cannot be
//! deserialized from transport; only a trusted admission service constructs them.
use crate::{
AgentPlanDisplayName, AgentPlanId, LogicalRequestId, ObservationQueryError, WorkspaceId,
};
use serde::{Deserialize, Serialize};
use std::collections::BTreeSet;
#[derive(Clone, Debug)]
pub struct ObservationReaderContext {
cancelled: std::sync::Arc<std::sync::atomic::AtomicBool>,
workspace: WorkspaceId,
subject: String,
allowed_runs: Option<BTreeSet<String>>,
read_content: bool,
search_content: bool,
authorization_generation: u64,
expires_at_ms: i64,
query_deadline: Option<std::time::Instant>,
}
impl ObservationReaderContext {
/// A composed analysis shares one budget across its existing read owners.
/// This trusted context is never deserialized from a client request.
pub fn with_query_deadline(mut self, deadline: std::time::Instant) -> Self {
self.query_deadline =
Some(deadline.min(std::time::Instant::now() + std::time::Duration::from_millis(500)));
self
}
pub fn query_deadline(&self) -> Option<std::time::Instant> {
self.query_deadline
}
/// Cancels this observation only; never cancels an Agent, Worker or model.
pub fn cancel(&self) {
self.cancelled
.store(true, std::sync::atomic::Ordering::Release);
}
pub fn is_cancelled(&self) -> bool {
self.cancelled.load(std::sync::atomic::Ordering::Acquire)
}
pub fn workspace(&self) -> &WorkspaceId {
&self.workspace
}
pub fn allowed_runs(&self) -> Option<&BTreeSet<String>> {
self.allowed_runs.as_ref()
}
/// Only a trusted local-user authorization issuer may construct this context.
pub fn local_user(
workspace: WorkspaceId,
subject: String,
authorization_generation: u64,
expires_at_ms: i64,
read_content: bool,
search_content: bool,
) -> Result<Self, ObservationQueryError> {
if !identifier(&subject)
|| expires_at_ms < 0
|| WorkspaceId::parse(workspace.as_str()).is_err()
{
return Err(ObservationQueryError::InvalidQuery);
}
Ok(Self {
cancelled: Default::default(),
workspace,
subject,
allowed_runs: None,
read_content,
search_content,
authorization_generation,
expires_at_ms,
query_deadline: None,
})
}
/// Caller must supply the allowed runs from current verified run admission.
pub fn run_scoped(
workspace: WorkspaceId,
subject: String,
authorization_generation: u64,
expires_at_ms: i64,
allowed_runs: BTreeSet<String>,
read_content: bool,
search_content: bool,
) -> Result<Self, ObservationQueryError> {
if allowed_runs.is_empty()
|| allowed_runs.len() > 200
|| allowed_runs.iter().any(|id| !identifier(id))
{
return Err(ObservationQueryError::InvalidQuery);
}
let mut reader = Self::local_user(
workspace,
subject,
authorization_generation,
expires_at_ms,
read_content,
search_content,
)?;
reader.allowed_runs = Some(allowed_runs);
Ok(reader)
}
pub fn check(
&self,
now_ms: i64,
content: bool,
search: bool,
) -> Result<(), ObservationQueryError> {
if self
.query_deadline
.is_some_and(|deadline| std::time::Instant::now() >= deadline)
{
return Err(ObservationQueryError::ReadTimeout);
}
if self.is_cancelled() {
return Err(ObservationQueryError::Unavailable);
}
if now_ms < 0
|| now_ms >= self.expires_at_ms
|| content && !self.read_content
|| search && !self.search_content
{
return Err(ObservationQueryError::Unauthorized);
}
Ok(())
}
pub fn binding(&self) -> Result<String, ObservationQueryError> {
crate::CanonicalDigest::of(&(
&self.workspace,
&self.subject,
&self.allowed_runs,
self.read_content,
self.search_content,
self.authorization_generation,
))
.map(|digest| digest.to_string())
.map_err(|_| ObservationQueryError::InvalidQuery)
}
/// Live pagination binds identity and admitted scope, while each page must
/// validate a fresh grant. An authorization revision alone is not a snapshot.
pub fn live_scope_binding(&self) -> Result<String, ObservationQueryError> {
crate::CanonicalDigest::of(&(
&self.workspace,
&self.subject,
&self.allowed_runs,
self.read_content,
self.search_content,
))
.map(|digest| digest.to_string())
.map_err(|_| ObservationQueryError::InvalidQuery)
}
/// Analysis facets share an admitted same-user population. Each facet still
/// checks its current content/search capability and supplied grant; flags
/// describing this particular read are not the population's identity.
pub fn analysis_scope_binding(&self) -> Result<String, ObservationQueryError> {
crate::CanonicalDigest::of(&(&self.workspace, &self.subject, &self.allowed_runs))
.map(|d| d.to_string())
.map_err(|_| ObservationQueryError::InvalidQuery)
}
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct RunObservationLink {
pub workspace_id: WorkspaceId,
pub request_id: LogicalRequestId,
pub task_id: String,
pub run_id: String,
pub producer_epoch: String,
pub source_event_id: String,
pub plan_id: String,
pub plan_revision: String,
pub publication_ref: String,
pub harness_id: String,
pub protocol_kind: String,
pub native_session_id: Option<String>,
pub native_turn_id: Option<String>,
/// Opaque caller-supplied provenance only; it is not a verified parent session or authority.
pub parent_context_ref: Option<String>,
pub continued_from_run_id: Option<String>,
}
#[derive(schemars::JsonSchema, Clone, Debug, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ObservationRequestQuery {
pub from_ms: i64,
pub to_ms: i64,
pub session_id: Option<String>,
/// Optional exact request locator. This is independent of page position so a
/// persisted quality sample can open evidence that is no longer on the first
/// timeline page.
#[serde(default)]
pub request_id: Option<String>,
pub limit: u16,
pub cursor: Option<String>,
#[serde(default)]
pub agent_id: Option<String>,
#[serde(default)]
pub plan_id: Option<String>,
#[serde(default)]
pub native_model: Option<String>,
#[serde(default)]
pub outcome: Option<String>,
#[serde(default)]
pub only_model_switch: bool,
}
#[derive(schemars::JsonSchema, Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ObservationRoutingContextStateV1 {
Recorded,
RecordedFixed,
Unavailable,
Conflicted,
}
#[derive(schemars::JsonSchema, Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ObservationRoutingContextNameStateV1 {
Recorded,
Unavailable,
}
#[derive(schemars::JsonSchema, Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ObservationRoutingContextV1 {
pub state: ObservationRoutingContextStateV1,
pub plan_id: Option<String>,
pub plan_revision: Option<String>,
pub display_name: Option<String>,
pub name_state: ObservationRoutingContextNameStateV1,
}
impl ObservationRoutingContextV1 {
pub fn from_execution_trust(trust: &super::FrozenExecutionTrustV1) -> Self {
match (&trust.route, &trust.agent_plan_id) {
(crate::ModelRequestRouteV2::Plan { revision, .. }, Some(plan_id)) => Self::recorded(
plan_id.as_str().to_owned(),
revision.to_string(),
trust.plan_display_name.clone(),
),
(crate::ModelRequestRouteV2::Fixed { .. }, None)
if trust.plan_display_name.is_none() =>
{
Self {
state: ObservationRoutingContextStateV1::RecordedFixed,
..Self::unavailable()
}
}
_ => Self::unavailable(),
}
}
pub fn unavailable() -> Self {
Self {
state: ObservationRoutingContextStateV1::Unavailable,
plan_id: None,
plan_revision: None,
display_name: None,
name_state: ObservationRoutingContextNameStateV1::Unavailable,
}
}
pub fn conflicted() -> Self {
Self {
state: ObservationRoutingContextStateV1::Conflicted,
..Self::unavailable()
}
}
pub fn recorded(plan_id: String, plan_revision: String, display_name: Option<String>) -> Self {
let name_state = if display_name.is_some() {
ObservationRoutingContextNameStateV1::Recorded
} else {
ObservationRoutingContextNameStateV1::Unavailable
};
Self {
state: ObservationRoutingContextStateV1::Recorded,
plan_id: Some(plan_id),
plan_revision: Some(plan_revision),
display_name,
name_state,
}
}
pub fn valid(&self) -> bool {
match self.state {
ObservationRoutingContextStateV1::Recorded => {
self.plan_id
.as_deref()
.is_some_and(|value| AgentPlanId::parse(value).is_ok())
&& self.plan_revision.as_deref().is_some_and(|value| {
value
.parse::<u64>()
.is_ok_and(|revision| revision > 0 && revision.to_string() == value)
})
&& match (&self.display_name, &self.name_state) {
(Some(name), ObservationRoutingContextNameStateV1::Recorded) => {
AgentPlanDisplayName::parse(name.clone()).is_ok()
}
(None, ObservationRoutingContextNameStateV1::Unavailable) => true,
_ => false,
}
}
ObservationRoutingContextStateV1::RecordedFixed
| ObservationRoutingContextStateV1::Unavailable
| ObservationRoutingContextStateV1::Conflicted => {
self.plan_id.is_none()
&& self.plan_revision.is_none()
&& self.display_name.is_none()
&& self.name_state == ObservationRoutingContextNameStateV1::Unavailable
}
}
}
}
#[derive(schemars::JsonSchema, Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
pub struct ObservedRequestSummary {
pub session_id: String,
pub request_id: String,
pub started_at_ms: i64,
pub outcome: Option<String>,
pub receipt_id: Option<String>,
pub run_id: Option<String>,
/// Opaque caller-provided navigation provenance, never interpreted as authority.
pub parent_context_ref: Option<String>,
/// Internal generated turn ids are deliberately absent.
pub native_turn_id: Option<String>,
pub relation_conflicted: bool,
pub routing_context: ObservationRoutingContextV1,
pub attempted_model_count: u32,
pub within_request_fallback: Option<bool>,
pub final_native_model: Option<String>,
/// None means adjacency or accepted-model evidence is incomplete.
pub between_turn_model_change: Option<bool>,
pub previous_native_turn_id: Option<String>,
pub previous_turn_model: Option<String>,
pub turn_final_native_model: Option<String>,
}
#[derive(schemars::JsonSchema, Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
pub struct ObservationRequestPage {
pub requests: Vec<ObservedRequestSummary>,
pub next_cursor: Option<String>,
}
fn identifier(value: &str) -> bool {
!value.is_empty() && value.len() <= 256 && !value.chars().any(char::is_control)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn scope_and_permissions_bind_cursors_and_expiry_is_exclusive() {
let reader = ObservationReaderContext::run_scoped(
WorkspaceId::default(),
"worker".into(),
1,
100,
["run-a".into()].into_iter().collect(),
false,
false,
)
.unwrap();
assert!(reader.check(99, false, false).is_ok());
assert_eq!(
reader.check(100, false, false),
Err(ObservationQueryError::Unauthorized)
);
assert_eq!(
reader.check(1, true, false),
Err(ObservationQueryError::Unauthorized)
);
assert_eq!(
reader.check(1, false, true),
Err(ObservationQueryError::Unauthorized)
);
let other = ObservationReaderContext::run_scoped(
WorkspaceId::default(),
"worker".into(),
1,
100,
["run-b".into()].into_iter().collect(),
false,
false,
)
.unwrap();
assert_ne!(reader.binding().unwrap(), other.binding().unwrap());
let revoked = ObservationReaderContext::run_scoped(
WorkspaceId::default(),
"worker".into(),
2,
100,
["run-a".into()].into_iter().collect(),
false,
false,
)
.unwrap();
assert_ne!(reader.binding().unwrap(), revoked.binding().unwrap());
}
#[test]
fn legacy_session_summary_defaults_correlation_to_unknown() {
let summary: ObservationSessionSummaryV2 = serde_json::from_value(serde_json::json!({
"session_id":"session",
"agent_id":"",
"first_request_at_ms":1,
"last_request_at_ms":2,
"request_count":1,
"fallback_request_count":0,
"unknown_model_request_count":0,
"content_completeness":"unknown"
}))
.unwrap();
assert_eq!(
summary.correlation_kind,
ObservationSessionCorrelationKindV1::Unknown
);
}
#[test]
fn routing_context_wire_shape_rejects_guessed_or_inconsistent_history() {
let exact = ObservationRoutingContextV1::recorded(
"plan/coding".into(),
"17".into(),
Some("Coding route".into()),
);
assert!(exact.valid());
let value = serde_json::to_value(&exact).unwrap();
assert_eq!(value["state"], "recorded");
assert_eq!(value["name_state"], "recorded");
let mut invalid_revision = exact.clone();
invalid_revision.plan_revision = Some("017".into());
assert!(!invalid_revision.valid());
let mut inconsistent = exact;
inconsistent.display_name = None;
assert!(!inconsistent.valid());
assert!(ObservationRoutingContextV1::conflicted().valid());
}
}
/// A small current valuation projection. Quote and attempt detail are separate
/// from this summary so a request with many attempts cannot expand one response.
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ObservationValuationSummaryV2 {
pub schema: String,
pub request_id: LogicalRequestId,
pub input_revision: u64,
pub settled_revision: Option<u64>,
pub pending: bool,
pub terminal_observed: bool,
pub facts_partial: bool,
pub unknown_attempt_count: Option<u64>,
pub amounts: Vec<ObservationValuationAmountV2>,
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ObservationValuationAmountV2 {
pub currency: String,
pub valuation_kind: crate::PriceValuationKindV1,
pub known_sum_micros: Option<u64>,
pub coverage: ObservationMetricCoverageV2,
pub missing_attempt_count: u64,
}
#[derive(schemars::JsonSchema, Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ObservationMetricCoverageV2 {
Complete,
Partial,
Unknown,
}
#[derive(schemars::JsonSchema, Clone, Debug, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ObservationSearchQueryV2 {
#[serde(default)]
pub agent_id: Option<String>,
#[serde(default)]
pub plan_id: Option<String>,
#[serde(default)]
pub native_model: Option<String>,
#[serde(default)]
pub outcome: Option<String>,
#[serde(default)]
pub only_model_switch: bool,
pub from_ms: i64,
pub to_ms: i64,
pub session_id: Option<String>,
pub keyword: String,
pub limit: u16,
pub cursor: Option<String>,
}
#[derive(schemars::JsonSchema, Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ObservationTextAnchorV2 {
pub session_id: String,
pub request_id: String,
pub native_turn_id: Option<String>,
pub message_occurrence_id: String,
pub content_id: String,
pub original_text_offset: u64,
pub match_kind: String,
}
#[derive(schemars::JsonSchema, Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ObservationSearchPageV2 {
pub hits: Vec<ObservationTextAnchorV2>,
pub next_cursor: Option<String>,
pub index_partial: bool,
pub budget_exhausted: bool,
}
/// Live conversation results, distinct from released occurrence pagination.
#[derive(schemars::JsonSchema, Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ObservationSessionSearchPageV1 {
pub hits: Vec<ObservationTextAnchorV2>,
pub next_cursor: Option<String>,
pub index_partial: bool,
}
#[derive(schemars::JsonSchema, Clone, Debug, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ObservationContentQueryV2 {
#[serde(default)]
pub anchor_offset: Option<u64>,
pub request_id: LogicalRequestId,
pub content_id: String,
pub cursor: Option<String>,
}
#[derive(schemars::JsonSchema, Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ObservationContentPageV2 {
pub request_id: LogicalRequestId,
pub content_id: String,
pub message_occurrence_id: String,
pub media_type: String,
pub original_digest: String,
pub original_byte_count: u64,
pub direction: String,
pub downstream_delivery: Option<String>,
pub state: String,
pub chunks: Vec<ObservationTextChunkV2>,
pub next_cursor: Option<String>,
}
#[derive(schemars::JsonSchema, Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ObservationTextChunkV2 {
pub original_byte_offset: u64,
pub text: String,
}
#[derive(schemars::JsonSchema, Clone, Debug, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ObservationFactsQueryV2 {
#[serde(default, skip_serializing_if = "routing_observations_disabled")]
pub include_routing_observations: bool,
pub request_id: LogicalRequestId,
pub limit: u16,
pub cursor: Option<String>,
}
#[derive(schemars::JsonSchema, Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ObservationSafeFactV2 {
/// Internal supported-format evidence. Never exposed by the public facts reader.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub pre_applicability_schema_digest: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub decision_protocol: Option<super::DecisionProtocolV1>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub routing_observation: Option<super::ObservationRoutingDecisionV1>,
pub event_id: String,
pub sequence: u64,
pub original_digest: String,
/// Safe routing identity projected from the request-frozen execution trust. This remains
/// after sensitive fact and receipt bodies are deleted; legacy rows decode without it.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub routing_context: Option<ObservationRoutingContextV1>,
pub occurred_at_ms: Option<i64>,
pub event_kind: String,
pub attempt_ordinal: Option<u32>,
pub native_model: Option<String>,
pub input_tokens: Option<u64>,
pub output_tokens: Option<u64>,
pub cache_read_tokens: Option<u64>,
pub cache_write_tokens: Option<u64>,
pub reasoning_tokens: Option<u64>,
pub outcome: Option<String>,
pub sensitive_fields_deleted: bool,
}
fn routing_observations_disabled(value: &bool) -> bool {
!value
}
#[derive(schemars::JsonSchema, Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ObservationFactsPageV2 {
pub facts: Vec<ObservationSafeFactV2>,
pub next_cursor: Option<String>,
pub projection_partial: bool,
}
/// Session-level summaries contain only observations visible to this reader.
#[derive(schemars::JsonSchema, Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
pub struct ObservationSessionPageV2 {
pub sessions: Vec<ObservationSessionSummaryV2>,
pub next_cursor: Option<String>,
}
#[derive(
schemars::JsonSchema, Clone, Copy, Debug, Default, Eq, PartialEq, Serialize, Deserialize,
)]
#[serde(rename_all = "snake_case")]
pub enum ObservationSessionCorrelationKindV1 {
AgentSupplied,
VerifiedWorker,
Inferred,
RequestScoped,
#[default]
Unknown,
}
#[derive(schemars::JsonSchema, Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
pub struct ObservationSessionSummaryV2 {
pub session_id: String,
pub agent_id: String,
pub first_request_at_ms: i64,
pub last_request_at_ms: i64,
pub request_count: u64,
pub fallback_request_count: u64,
pub unknown_model_request_count: u64,
pub content_completeness: super::ContentCompleteness,
#[serde(default)]
pub correlation_kind: ObservationSessionCorrelationKindV1,
}