protocol

type APIPermissionGrant struct {
	Resource   string `json:"resource"`
	ResourceID uint   `json:"resource_id"`
	Action     string `json:"action"`
}

type APIRoleSet struct {
	RoleIDs []uint `json:"role_ids"`
}

type APIRoleSetFetchRequest struct {
	PrincipalID uint `json:"principal_id"`
}

type APIRoleSetFetchResult struct {
	PrincipalID uint       `json:"principal_id"`
	Exists      bool       `json:"exists"`
	RoleSet     APIRoleSet `json:"role_set"`
}

type APIRoleSetInvalidate struct {
	PrincipalID uint `json:"principal_id"`
}

type APITraceEntry = apiattempt.APIExecutionTrace

type APIUpstreamCredential struct {
	BearerToken   string `json:"bearer_token,omitempty"`
	HeaderName    string `json:"header_name,omitempty"`
	HeaderValue   string `json:"header_value,omitempty"`
	QueryName     string `json:"query_name,omitempty"`
	QueryValue    string `json:"query_value,omitempty"`
	BasicUsername string `json:"basic_username,omitempty"`
	BasicPassword string `json:"basic_password,omitempty"`
}

type APIUsageEntry struct {
	RequestID string `json:"request_id"`
	UserID    uint   `json:"user_id"`
	TokenID   uint   `json:"token_id"`
	TokenName string `json:"token_name"`
	ClientIP  string `json:"client_ip"`

	APIServiceID  uint   `json:"api_service_id"`
	APIRouteID    uint   `json:"api_route_id"`
	APIUpstreamID uint   `json:"api_upstream_id"`
	ServiceName   string `json:"service_name"`
	RouteName     string `json:"route_name"`
	UpstreamName  string `json:"upstream_name"`

	Protocol string `json:"protocol"`
	Method   string `json:"method"`
	Subpath  string `json:"subpath"`

	SourceAgentID    string `json:"source_agent_id"`
	ExecutionAgentID string `json:"execution_agent_id"`
	AgentRouteID     uint   `json:"agent_route_id"`
	AgentRoutePath   string `json:"agent_route_path"`

	StatusCode         int   `json:"status_code"`
	DurationMs         int   `json:"duration_ms"`
	FirstByteMs        int   `json:"first_byte_ms"`
	RequestBytes       int64 `json:"request_bytes"`
	ResponseBytes      int64 `json:"response_bytes"`
	WebSocketCloseCode int   `json:"websocket_close_code"`

	ProviderDispatchKnown bool   `json:"provider_dispatch_known"`
	ProviderDispatched    bool   `json:"provider_dispatched"`
	QuotaGateDecision     string `json:"quota_gate_decision"`
	ErrorStage            string `json:"error_stage"`
	ErrorCode             string `json:"error_code"`
	ErrorMessage          string `json:"error_message,omitempty"`

	RateLimitDecision      string                `json:"rate_limit_decision"`
	RateLimitWaitMs        int                   `json:"rate_limit_wait_ms"`
	RateLimitReason        string                `json:"rate_limit_reason"`
	RateLimitHits          []models.RateLimitHit `json:"rate_limit_hits,omitempty"`
	RateLimitHitTotal      int                   `json:"rate_limit_hit_total"`
	RateLimitHitsTruncated bool                  `json:"rate_limit_hits_truncated"`

	Trace     *APITraceEntry `json:"trace,omitempty"`
	Timestamp int64          `json:"timestamp"`
}

type Address struct {
	URL string `json:"url"`
	Tag string `json:"tag"`
}

type AgentCapabilitiesUpdate struct {
	AgentID      string   `json:"agent_id"`
	Capabilities []string `json:"capabilities"`
}

type AgentDirectAddressesUpdate struct {
	MasterInstanceID  string    `json:"master_instance_id"`
	AgentID           string    `json:"agent_id"`
	SessionGeneration uint64    `json:"session_generation"`
	Sequence          uint64    `json:"sequence"`
	HTTPAddresses     []Address `json:"http_addresses"`
}

type AuthBootstrapResponse struct {
	MasterInstanceID string                `json:"master_instance_id"`
	Capabilities     []string              `json:"capabilities"`
	SigningKeys      []agentauth.PublicKey `json:"signing_keys"`
}

type CacheEntityStats struct {
	Kind          string           `json:"kind,omitempty"` // "lru" | "index"；旧 agent 上报空串，前端按 lru 兜底
	Hits          int64            `json:"hits"`
	Misses        int64            `json:"misses"`
	Evictions     int64            `json:"evictions"`
	NegativeHits  int64            `json:"negative_hits"`
	LoadErrors    int64            `json:"load_errors"`
	Invalidations int64            `json:"invalidations"`
	Size          int              `json:"size"`
	Capacity      int              `json:"capacity"`
	Extra         map[string]int64 `json:"extra,omitempty"` // 索引细分，如 {"limiters":12,"bindings":30}
}

type DirectProbeResult struct {
	TargetAgentID      string      `json:"target_agent_id"`
	AddressFingerprint string      `json:"address_fingerprint"`
	Network            string      `json:"network"`
	Identity           string      `json:"identity"`
	Eligible           bool        `json:"eligible"`
	LatencyMS          int64       `json:"latency_ms"`
	CheckedAt          int64       `json:"checked_at"`
	ReasonCode         string      `json:"reason_code,omitempty"`
	Stage              string      `json:"stage,omitempty"`
	Policy             ProbePolicy `json:"policy"`
	PolicyDisabled     bool        `json:"policy_disabled"`
	PolicyReasonCode   string      `json:"policy_reason_code,omitempty"`
}

type DirectProbeTarget struct {
	TargetAgentID      string      `json:"target_agent_id"`
	Addresses          []Address   `json:"addresses"`
	EffectiveProxy     string      `json:"effective_proxy"`
	AddressFingerprint string      `json:"address_fingerprint"`
	TargetGeneration   uint64      `json:"target_generation"`
	Policy             ProbePolicy `json:"policy"`
}

type FetchEntityRequest struct {
	Entity string `json:"entity"`
	Key    string `json:"key"`
}

type FetchEntityResponse struct {
	Found bool            `json:"found"`
	Data  json.RawMessage `json:"data,omitempty"`
	Side  json.RawMessage `json:"side,omitempty"`
}

type ForceFullSyncResponse struct {
	Version    int64 `json:"version"`
	DurationMs int64 `json:"duration_ms"`
}

type FullSyncRequest struct {
	Entity        string `json:"entity"`
	Page          int    `json:"page,omitempty"`
	PageSize      int    `json:"page_size"`
	AfterID       uint   `json:"after_id,omitempty"`
	SnapshotMaxID uint   `json:"snapshot_max_id,omitempty"`
	BaseVersion   int64  `json:"base_version,omitempty"`
}

type FullSyncResponse struct {
	Items            []byte `json:"items"`
	Total            int64  `json:"total"`
	Page             int    `json:"page,omitempty"`
	HasMore          bool   `json:"has_more"`
	Version          int64  `json:"version"`
	Keyset           bool   `json:"keyset,omitempty"`
	LastID           uint   `json:"last_id,omitempty"`
	SnapshotMaxID    uint   `json:"snapshot_max_id,omitempty"`
	BaseVersion      int64  `json:"base_version,omitempty"`
	SnapshotContract string `json:"snapshot_contract,omitempty"`
}

type GetVersionResponse struct {
	Version int64 `json:"version"`
}

type HeartbeatParams struct {
	Uptime               int64         `json:"uptime"`
	CachedTokens         int           `json:"cached_tokens"`
	CachedChannels       int           `json:"cached_channels"`
	CachedModels         int           `json:"cached_models"`
	CachedGlobalRoutings int           `json:"cached_global_routings"`
	CachedUserRoutings   int           `json:"cached_user_routings"`
	ActiveConnections    int           `json:"active_connections"`
	Version              int64         `json:"version"`
	PendingUsage         int           `json:"pending_usage,omitempty"`
	Capabilities         []string      `json:"capabilities,omitempty"`
	Relay                *RelayRuntime `json:"relay,omitempty"`

	HTTPAddresses json.RawMessage `json:"http_addresses,omitempty"`
	Tags          string          `json:"tags,omitempty"`
	ProxyURL      string          `json:"proxy_url,omitempty"`
	ListenPort    int             `json:"listen_port,omitempty"`

	CacheStats map[string]CacheEntityStats `json:"cache_stats,omitempty"`
}

type LimiterBucketStat struct {
	LimiterID   uint   `json:"limiter_id"`
	Name        string `json:"name"`
	Bucket      string `json:"bucket"`
	Metric      string `json:"metric"` // concurrency | rate
	KeyBy       string `json:"key_by"`
	Occupied    int64  `json:"occupied"` // 并发:当前占用; 速率:当前窗口已用
	Capacity    int64  `json:"capacity"`
	Waiters     int64  `json:"waiters"`
	WindowEndMs int64  `json:"window_end_ms"` // 速率桶本窗口复位时刻(unix ms);并发为 0
}

type ManualProbeProgress struct {
	ProbeID     string `json:"probe_id"`
	State       string `json:"state"`
	TargetTotal int    `json:"target_total"`
	Remaining   int    `json:"remaining"`
	StartedAt   int64  `json:"started_at,omitempty"`
	CompletedAt int64  `json:"completed_at,omitempty"`
}

type OperationAck struct {
	OperationID string `json:"operation_id"`
	State       string `json:"state"`
	SnapshotSeq uint64 `json:"snapshot_seq"`
}

type OperationRequest struct {
	AgentID                   string `json:"agent_id"`
	Operation                 string `json:"operation"`
	TargetAgentID             string `json:"target_agent_id,omitempty"`
	RequestID                 string `json:"request_id,omitempty"`
	ExpectedEpoch             string `json:"expected_epoch"`
	ExpectedControlGeneration uint64 `json:"expected_control_generation,omitempty"`
	ExpectedRelayGeneration   uint64 `json:"expected_relay_generation,omitempty"`
}

type PrivateChannelInvalidatePayload struct {
	Action          string `json:"action"` // "invalidate"
	AffectedUserIDs []uint `json:"affected_user_ids"`
}

type ProbeAck struct {
	ProbeID         string     `json:"probe_id"`
	ProbeGeneration uint64     `json:"probe_generation"`
	Scope           ProbeScope `json:"scope"`
	State           string     `json:"state"`
	TargetTotal     int        `json:"target_total"`
	SnapshotSeq     uint64     `json:"snapshot_seq"`
}

type ProbePolicy = wire.ProbePolicy

type ProbeScope struct {
	Kind           string   `json:"kind"`
	Tag            string   `json:"tag,omitempty"`
	TargetAgentIDs []string `json:"target_agent_ids,omitempty"`
}

type PublicRouteError struct {
	Code      string `json:"code"`
	Stage     string `json:"stage"`
	RequestID string `json:"request_id"`
	Message   string `json:"message"`
}

type RelayActiveRuntime struct {
	URI               string `json:"uri"`
	ActiveGeneration  uint64 `json:"active_generation"`
	SessionGeneration uint64 `json:"session_generation"`
	ConnectedAt       int64  `json:"connected_at"`
	Streams           int    `json:"streams"`
	RetryAt           int64  `json:"retry_at"`
}

type RelayDesiredRuntime struct {
	Mode              string `json:"mode"`
	ConfiguredURI     string `json:"configured_uri"`
	EffectiveURI      string `json:"effective_uri"`
	DesiredGeneration uint64 `json:"desired_generation"`
}

type RelayProbeResult struct {
	TargetAgentID    string          `json:"target_agent_id"`
	State            RelayProbeState `json:"state"`
	Stage            RelayProbeStage `json:"stage,omitempty"`
	LatencyMS        int64           `json:"latency_ms"`
	CheckedAt        int64           `json:"checked_at"`
	ReasonCode       string          `json:"reason_code,omitempty"`
	Policy           ProbePolicy     `json:"policy"`
	PolicyDisabled   bool            `json:"policy_disabled"`
	PolicyReasonCode string          `json:"policy_reason_code,omitempty"`
}

type RelayProbeStage string

type RelayProbeState string

type RelayProbeTarget struct {
	TargetAgentID         string      `json:"target_agent_id"`
	SourceRelayGeneration uint64      `json:"source_relay_generation"`
	TargetRelayGeneration uint64      `json:"target_relay_generation"`
	Policy                ProbePolicy `json:"policy"`
}

type RelayRecentError struct {
	Code       string `json:"code"`
	Stage      string `json:"stage"`
	Message    string `json:"message"`
	OccurredAt int64  `json:"occurred_at"`
	Count      uint64 `json:"count"`
}

type RelayRuntime struct {
	Support             string              `json:"support"`
	Config              string              `json:"config"`
	Availability        string              `json:"availability"`
	AcceptingNewStreams bool                `json:"accepting_new_streams"`
	Convergence         string              `json:"convergence"`
	Desired             RelayDesiredRuntime `json:"desired"`
	Active              RelayActiveRuntime  `json:"active"`
	LastError           string              `json:"last_error,omitempty"`
	RecentErrors        []RelayRecentError  `json:"recent_errors,omitempty"`
}

type RelayTicketRequest struct {
	DesiredGeneration uint64 `json:"desired_generation"`
}

type ReportedUsage struct {
	LLM *UsageLogEntry `json:"llm,omitempty"`
	API *APIUsageEntry `json:"api,omitempty"`
}

type RouteEdgeDigest struct {
	Generation     uint64              `json:"generation"`
	Edges          []RouteEdgeSnapshot `json:"edges"`
	CoveredThrough uint64              `json:"covered_through,omitempty"`
}

type RouteEdgeSnapshot struct {
	TargetAgentID      string `json:"target_agent_id"`
	RouteID            uint   `json:"route_id"`
	SelectorKind       string `json:"selector_kind"`
	LastUsedAt         int64  `json:"last_used_at"`
	LastDirectResult   string `json:"last_direct_result"`
	AddressFingerprint string `json:"address_fingerprint"`
	SuccessCount       uint64 `json:"success_count"`
	LatencyTotalMS     uint64 `json:"latency_total_ms"`
}

type RouteEvent struct {
	RequestID          string                    `json:"request_id,omitempty"`
	TargetAgentID      string                    `json:"target_agent_id"`
	RouteID            uint                      `json:"route_id"`
	SelectorKind       string                    `json:"selector_kind"`
	PathKind           string                    `json:"path_kind"`
	Result             string                    `json:"result"`
	Stage              string                    `json:"stage"`
	ReasonCode         string                    `json:"reason_code"`
	CommitState        string                    `json:"commit_state"`
	AddressFingerprint string                    `json:"address_fingerprint"`
	DurationMS         int64                     `json:"duration_ms"`
	ObservedAt         int64                     `json:"observed_at"`
	Sequence           uint64                    `json:"sequence,omitempty"`
	Failures           []RouteFailureObservation `json:"failures,omitempty"`
}

type RouteFailureObservation struct {
	PathKind    string `json:"path_kind"`
	Stage       string `json:"stage"`
	CommitState string `json:"commit_state"`
	ReasonCode  string `json:"reason_code"`
}

type RouteTelemetryBatch struct {
	Generation uint64       `json:"generation"`
	Events     []RouteEvent `json:"events"`
}

type RoutingMember struct {
	Ref      string `json:"ref"`
	Priority int    `json:"priority"`
	Weight   int    `json:"weight"`
}

type RoutingOwner struct {
	UserID  uint
	TokenID uint
}

type SyncPushParams struct {
	Entity  string `json:"entity"`
	Action  string `json:"action"`
	Data    []byte `json:"data"`
	Version int64  `json:"version"`
}

type SyncedAPIRole struct {
	ID          uint                 `json:"id"`
	Name        string               `json:"name"`
	Permissions []APIPermissionGrant `json:"permissions"`
}

type SyncedAPIRoute struct {
	ID                    uint     `json:"id"`
	ServiceID             uint     `json:"service_id"`
	BackendID             uint     `json:"backend_id"`
	Slug                  string   `json:"slug"`
	Protocols             []string `json:"protocols"`
	AllowedMethods        []string `json:"allowed_methods"`
	WebSocketSubprotocols []string `json:"websocket_subprotocols"`
	UpstreamPath          string   `json:"upstream_path"`
	ForwardSubpath        bool     `json:"forward_subpath"`
	Status                int      `json:"status"`
}

type SyncedAPIService struct {
	ID            uint   `json:"id"`
	Slug          string `json:"slug"`
	Name          string `json:"name"`
	ConsumesQuota bool   `json:"consumes_quota"`
	Status        int    `json:"status"`
}

type SyncedAPIUpstream struct {
	ID             uint                  `json:"id"`
	BackendID      uint                  `json:"backend_id"`
	Name           string                `json:"name"`
	BaseURL        string                `json:"base_url"`
	AuthType       string                `json:"auth_type"`
	Credential     APIUpstreamCredential `json:"credential"`
	HeaderOverride map[string]string     `json:"header_override"`
	ProxyURL       string                `json:"proxy_url"`
	Priority       int                   `json:"priority"`
	Weight         int                   `json:"weight"`
	Status         int                   `json:"status"`
}

type SyncedPrivateChannel struct {
	models.ChannelCore

	OwnerID      uint              `json:"owner_id"`
	KeyPlaintext string            `json:"key"`
	Models       []string          `json:"models"`
	ModelMapping map[string]string `json:"model_mapping"`
}

type SyncedRouting struct {
	ID      uint            `json:"id"`
	Name    string          `json:"name"`
	Scope   string          `json:"scope"`
	UserID  uint            `json:"user_id"`
	TokenID uint            `json:"token_id"`
	Members []RoutingMember `json:"members"`
	Enabled bool            `json:"enabled"`
}

type SyncedUser struct {
	ID      uint  `json:"id"`
	GroupID uint  `json:"group_id"`
	Quota   int64 `json:"quota"`
}

type TicketResponse struct {
	Token     string `json:"token"`
	ExpiresAt int64  `json:"expires_at"`
}

type TokenFetchSide struct {
	SchemaVersion int              `json:"schema_version"`
	User          *SyncedUser      `json:"user,omitempty"`
	TokenRoutings *TokenRoutingMap `json:"token_routings,omitempty"`
}

type TokenRoutingMap struct {
	Routings map[string]*SyncedRouting `json:"routings"`
}

type UsageLogEntry struct {
	RequestID          string  `json:"request_id"`
	UserID             uint    `json:"user_id"`
	TokenID            uint    `json:"token_id"`
	ChannelID          uint    `json:"channel_id"`
	PrivateChannelID   uint    `json:"private_channel_id"`
	OwnerType          string  `json:"owner_type"`
	ModelName          string  `json:"model_name"`
	PromptTokens       int     `json:"prompt_tokens"`
	CompletionTokens   int     `json:"completion_tokens"`
	IsStream           bool    `json:"is_stream"`
	Duration           int     `json:"duration"`
	ClientIP           string  `json:"client_ip"`
	Timestamp          int64   `json:"timestamp"`
	ExecutionAgentID   *string `json:"execution_agent_id,omitempty"`
	RouteSourceAgentID string  `json:"route_source_agent_id,omitempty"`
	AgentRouteID       uint    `json:"agent_route_id,omitempty"`
	AgentRoutePath     string  `json:"agent_route_path,omitempty"`

	// Enhanced logging fields
	TokenName        string `json:"token_name"`
	UpstreamModel    string `json:"upstream_model"`
	FirstResponseMs  int    `json:"first_response_ms"`
	CacheReadTokens  int    `json:"cache_read_tokens"`
	CacheWriteTokens int    `json:"cache_write_tokens"`
	InboundProtocol  string `json:"inbound_protocol"`
	OutboundProtocol string `json:"outbound_protocol"`
	UseLegacy        bool   `json:"use_legacy"`
	Status           int    `json:"status"`
	ErrorMessage     string `json:"error_message,omitempty"`
	TraceData        string `json:"trace_data,omitempty"`
	Other            string `json:"other"`
	TokenSource      string `json:"token_source,omitempty"`
	RoutingName      string `json:"routing_name,omitempty"`

	TraceRetentionStatus models.TraceRetentionStatus `json:"trace_retention_status,omitempty"`

	// Channel affinity（渠道缓存粘性）
	AffinityStatus   string `json:"affinity_status,omitempty"` // "hit" | "fallback" | "none" | ""
	AffinityRecorded bool   `json:"affinity_recorded,omitempty"`

	ErrorStage         string `json:"error_stage,omitempty"`
	InboundDecodeMs    int    `json:"inbound_decode_ms,omitempty"`
	OutboundEncodeMs   int    `json:"outbound_encode_ms,omitempty"`
	UpstreamDispatchMs int    `json:"upstream_dispatch_ms,omitempty"`
	UpstreamDecodeMs   int    `json:"upstream_decode_ms,omitempty"`
	ClientEncodeMs     int    `json:"client_encode_ms,omitempty"`

	// PriceRatio 是 relay 选中的公共 channel 在请求时刻的计费倍率快照。
	// 零值 0(旧 agent 未发 / channel 未配)= 原价,settler 归一到 1.0。
	PriceRatio float64 `json:"price_ratio,omitempty"`

	// Free 是 relay 选中的公共 channel 在请求时刻的"免费渠道"标记快照。
	// private 行不填,保持 false。settler 见 true 则四桶成本清零。
	Free bool `json:"free,omitempty"`

	// FallbackChain 是本次请求的候选链路（每候选一条）；空表示无链路信息。
	FallbackChain []models.AttemptRecord `json:"fallback_chain,omitempty"`
	// AttemptTraces 是逐候选 mask 过的 header/body trace，index 对应 FallbackChain 的 Seq-1。
	// AttemptIndex assigned by settler from slice order until Task 5 adds the field.
	AttemptTraces []models.UsageLogTrace `json:"attempt_traces,omitempty"`

	// 限流决策（请求级 limiter）：Decision/WaitMs/Reason 标量 + Hits 命中明细。
	// 无命中时全为零值/空，omitempty 不上报。
	RateLimitDecision string                `json:"rate_limit_decision,omitempty"`
	RateLimitWaitMs   int                   `json:"rate_limit_wait_ms,omitempty"`
	RateLimitReason   string                `json:"rate_limit_reason,omitempty"`
	RateLimitHits     []models.RateLimitHit `json:"rate_limit_hits,omitempty"`

	// AutoDisableTriggers is internal Agent-to-Master transport state.
	AutoDisableTriggers []attemptproxy.ChannelAutoDisableTrigger `json:"auto_disable_triggers,omitempty"`
}

type UsageReport struct {
	AgentID     string          `json:"agent_id"`
	Logs        []UsageLogEntry `json:"logs,omitempty"`
	APIRequests []APIUsageEntry `json:"api_requests,omitempty"`
}

type UserQuotaSync struct {
	AgentID string       `json:"agent_id"`
	Users   []SyncedUser `json:"users"`
}

type UserRoutingMap struct {
	Routings map[string]*SyncedRouting `json:"routings"`
}

type VisiblePrivateChannelSet struct {
	UserID   uint                   `json:"user_id"`
	Channels []SyncedPrivateChannel `json:"channels"`
}