feat(plugins)!: expose account binding and selection roles to schedulers

Scheduler v4 reports session ownership separately from native selection preferences and pins. Only eligible candidates are annotated, and cache preferences do not imply a session binding.

BREAKING CHANGE: scheduler plugins must declare capability version 4 and accept the new candidate fields.

Co-authored-by: Codex <noreply@openai.com>
This commit is contained in:
Zyy
2026-11-17 16:48:06 +08:00
co-authored by Codex
parent 9f873f5ac2
commit 4d4c1e48ce
19 changed files with 214 additions and 45 deletions
@@ -982,11 +982,19 @@ impl AttemptContext {
model: Option<&str>,
candidates: &'a [AccountCandidate],
context: &mut AccountSelectionContext,
ownership: policy::AccountScheduleOwnership<'_>,
) -> Result<Option<AccountSelection<'a>>, policy::AccountPolicyError> {
match self.request.request_policy() {
Some(policy) => {
policy
.select_account(self.attempt_index, provider, model, candidates, context)
.select_account(
self.attempt_index,
provider,
model,
candidates,
context,
ownership,
)
.await
}
None => Ok(crate::account::AccountSelector.select(candidates, context)),
@@ -115,10 +115,29 @@ pub enum ModelRouteDecision {
Reject,
}
/// Provider 在本轮选号中已解析的归属,仅用于向插件投影候选关系
#[derive(Debug, Default, Clone, Copy)]
pub struct AccountScheduleOwnership<'a> {
pub bound_account: Option<&'a ProviderAccountId>,
pub follow_only: bool,
pub pinned_account: Option<&'a ProviderAccountId>,
}
/// 本轮内置选号如何对待这个候选;显式选号仍受宿主资格和固定归属约束
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AccountScheduleRole {
Ordinary,
Preferred,
FollowOnly,
Pinned,
}
/// 账号调度插件可见的单个候选事实,不包含凭据或账号资料
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AccountScheduleCandidate {
account_id: ProviderAccountId,
session_bound: bool,
role: AccountScheduleRole,
available: bool,
weight: u16,
in_flight: u32,
@@ -131,6 +150,16 @@ pub struct AccountScheduleCandidate {
}
impl AccountScheduleCandidate {
#[must_use]
pub const fn session_bound(&self) -> bool {
self.session_bound
}
#[must_use]
pub const fn role(&self) -> AccountScheduleRole {
self.role
}
#[must_use]
pub const fn available(&self) -> bool {
self.available
@@ -469,6 +498,7 @@ impl RequestPolicyContext {
model: Option<&str>,
candidates: &'a [AccountCandidate],
context: &mut AccountSelectionContext,
ownership: AccountScheduleOwnership<'_>,
) -> Result<Option<AccountSelection<'a>>, AccountPolicyError> {
let eligible = AccountSelector.policy_candidates(candidates, context);
if eligible.is_empty() {
@@ -476,19 +506,33 @@ impl RequestPolicyContext {
}
let projected = eligible
.iter()
.map(|candidate| AccountScheduleCandidate {
account_id: candidate.account.id().clone(),
available: AccountSelector
.scheduling_blocker(candidate, context)
.is_none(),
weight: candidate.account.weight().get(),
in_flight: candidate.signals.in_flight,
maximum_concurrency: context.concurrency_limit(candidate).get(),
last_started_at: candidate.signals.last_started_at,
quota_reset_at: candidate.signals.quota_reset_at,
quota_remaining_rank: candidate.signals.quota_remaining_rank,
failure_rate_basis_points: candidate.signals.failure_rate_basis_points,
first_output_latency_ms: candidate.signals.first_output_latency_ms,
.map(|candidate| {
let id = Some(candidate.account.id());
let session_bound = ownership.bound_account == id;
AccountScheduleCandidate {
session_bound,
role: if ownership.pinned_account == id {
AccountScheduleRole::Pinned
} else if session_bound && ownership.follow_only {
AccountScheduleRole::FollowOnly
} else if context.preferred_account.as_ref() == id {
AccountScheduleRole::Preferred
} else {
AccountScheduleRole::Ordinary
},
account_id: candidate.account.id().clone(),
available: AccountSelector
.scheduling_blocker(candidate, context)
.is_none(),
weight: candidate.account.weight().get(),
in_flight: candidate.signals.in_flight,
maximum_concurrency: context.concurrency_limit(candidate).get(),
last_started_at: candidate.signals.last_started_at,
quota_reset_at: candidate.signals.quota_reset_at,
quota_remaining_rank: candidate.signals.quota_remaining_rank,
failure_rate_basis_points: candidate.signals.failure_rate_basis_points,
first_output_latency_ms: candidate.signals.first_output_latency_ms,
}
})
.collect();
let decision = self
@@ -2352,6 +2352,7 @@ impl Provider for PolicySelectingProvider {
.map(UpstreamModelId::as_str),
&candidates,
&mut selection,
Default::default(),
)
.await
{
@@ -131,6 +131,7 @@ fn scheduler_can_override_soft_affinity_and_reports_the_override() {
Some("demo-model"),
&candidates,
&mut context(),
Default::default(),
)
.await
.unwrap()
@@ -156,6 +157,7 @@ fn delegated_scheduler_keeps_builtin_affinity() {
None,
&candidates,
&mut context(),
Default::default(),
)
.await
.unwrap()
@@ -195,6 +197,7 @@ fn explicit_plugin_choices_override_native_soft_affinity() {
None,
&candidates,
&mut selection_context,
Default::default(),
)
.await
.unwrap()
@@ -226,6 +229,7 @@ fn scheduler_cannot_select_outside_the_hard_bound_candidate_pool() {
None,
&candidates,
&mut context,
Default::default(),
)
.await;
assert!(matches!(result, Err(AccountPolicyError::Fault)));
@@ -257,6 +261,7 @@ fn filtered_delegation_preserves_native_weights_and_affinity_on_remaining_accoun
None,
&candidates,
&mut context,
Default::default(),
)
.await
.unwrap()
@@ -298,7 +303,8 @@ fn filtered_delegation_covers_busy_candidates_and_does_not_persist_between_selec
&ProviderKind::new("openai").unwrap(),
None,
&candidates,
&mut selection
&mut selection,
Default::default(),
)
.await
.unwrap()
@@ -316,6 +322,7 @@ fn filtered_delegation_covers_busy_candidates_and_does_not_persist_between_selec
None,
&candidates,
&mut context(),
Default::default(),
)
.await
.unwrap()
@@ -344,6 +351,7 @@ fn filtering_all_candidates_is_terminal_even_when_the_only_candidate_is_busy_or_
None,
&candidates,
&mut context,
Default::default(),
)
.await;
assert!(matches!(result, Err(AccountPolicyError::Filtered)));
@@ -368,6 +376,7 @@ fn filtering_ids_outside_the_host_candidate_pool_is_a_policy_fault() {
None,
&candidates,
&mut context,
Default::default(),
)
.await;
assert!(matches!(result, Err(AccountPolicyError::Fault)));
@@ -386,6 +395,7 @@ fn empty_filter_preserves_native_affinity_and_busy_candidates_cannot_be_picked()
None,
&candidates,
&mut context(),
Default::default(),
)
.await
.unwrap()
@@ -400,6 +410,7 @@ fn empty_filter_preserves_native_affinity_and_busy_candidates_cannot_be_picked()
None,
&candidates,
&mut context,
Default::default(),
)
.await;
assert!(matches!(result, Err(AccountPolicyError::Fault)));
@@ -4,7 +4,7 @@
"protocol_versions": [7],
"capabilities": [
{ "capability": "frontend_authentication", "versions": [2] },
{ "capability": "scheduler", "versions": [3] },
{ "capability": "scheduler", "versions": [4] },
{ "capability": "model_router", "versions": [2] },
{ "capability": "model_catalog", "versions": [2] },
{ "capability": "retry_policy", "versions": [2] },
@@ -7,8 +7,8 @@ use futures::future::BoxFuture;
use gateway_core::{
account::ProviderAccountId,
engine::policy::{
AccountScheduleDecision, AccountScheduleInput, ModelRouteDecision, ModelRouteInput,
RequestPolicyFault, RequestPolicyPlan,
AccountScheduleDecision, AccountScheduleInput, AccountScheduleRole, ModelRouteDecision,
ModelRouteInput, RequestPolicyFault, RequestPolicyPlan,
},
identity::ProviderKind,
operation::{Operation, ProviderHttpHeader},
@@ -20,6 +20,7 @@ use gateway_plugin_sdk::{
AccountScheduleCandidate as WireAccountScheduleCandidate,
AccountScheduleDecision as WireAccountScheduleDecision,
AccountScheduleRequest as WireAccountScheduleRequest,
AccountScheduleRole as WireAccountScheduleRole,
ModelRouteDecision as WireModelRouteDecision, ModelRouteRequest, PolicyHeader,
},
};
@@ -183,6 +184,13 @@ async fn schedule_with_entry(
.iter()
.map(|candidate| WireAccountScheduleCandidate {
account_id: candidate.account_id().as_str().to_owned(),
session_bound: candidate.session_bound(),
role: match candidate.role() {
AccountScheduleRole::Ordinary => WireAccountScheduleRole::Ordinary,
AccountScheduleRole::Preferred => WireAccountScheduleRole::Preferred,
AccountScheduleRole::FollowOnly => WireAccountScheduleRole::FollowOnly,
AccountScheduleRole::Pinned => WireAccountScheduleRole::Pinned,
},
available: candidate.available(),
weight: candidate.weight(),
in_flight: candidate.in_flight(),
@@ -682,6 +682,7 @@ async fn scheduler_cannot_pick_outside_the_host_projected_priority_tier() {
Some("upstream-a"),
&candidates,
&mut selection,
Default::default(),
)
.await
.unwrap()
@@ -306,6 +306,7 @@ async fn data_plane_http_callbacks_keep_the_frozen_body_budget_across_publicatio
None,
&[candidate("acct_high", 100)],
&mut selection_context(),
Default::default(),
)
.await
.unwrap();
@@ -1,7 +1,7 @@
//! 验证真实插件进程的候选过滤、繁忙投影与非法决定边界
use super::*;
use gateway_core::engine::policy::AccountPolicyError;
use gateway_core::engine::policy::{AccountPolicyError, AccountScheduleOwnership};
#[tokio::test]
async fn scheduler_filter_contract_covers_busy_candidates_and_rejects_out_of_scope_ids() {
@@ -44,6 +44,10 @@ async fn scheduler_filter_contract_covers_busy_candidates_and_rejects_out_of_sco
None,
&candidates,
&mut selection,
AccountScheduleOwnership {
bound_account: Some(candidates[0].account.id()),
..Default::default()
},
)
.await;
match expected {
@@ -60,8 +64,13 @@ async fn scheduler_filter_contract_covers_busy_candidates_and_rejects_out_of_sco
request["request"]["candidates"].as_array().unwrap().len(),
2
);
assert_eq!(request["request"]["candidates"][0]["available"], false);
assert_eq!(request["request"]["candidates"][1]["available"], true);
let candidates = &request["request"]["candidates"];
assert_eq!(candidates[0]["available"], false);
assert_eq!(candidates[0]["session_bound"], true);
assert_eq!(candidates[0]["role"], "preferred");
assert_eq!(candidates[1]["available"], true);
assert_eq!(candidates[1]["session_bound"], false);
assert_eq!(candidates[1]["role"], "ordinary");
drop(policy);
drop(generation);
super::super::wait_until_empty(cache.path()).await;
@@ -653,9 +653,20 @@ middleware 的 `next` 最多调用一次,重试与额外模型执行通过独
### 路由、调度与观察
`policy.route_model` 和 `policy.schedule_account` 只提出决定,宿主随后复核 Key 规则、模型能力、账号资格和租约。
`scheduler` 必须声明 `version: 3`。`candidates` 已按 Key 范围、模型权限、账号状态和原生续写绑定收窄,
`scheduler` 必须声明 `version: 4`。`candidates` 已按 Key 范围、模型权限、账号状态和原生续写绑定收窄,
同时包含暂时繁忙但可以等待的账号;`available` 表示本次可以立即尝试租约,不保证租约一定成功
每个候选的 `session_bound` 表示它是否为 Provider 已查到的本次会话绑定账号。仅匹配缓存偏好不算会话绑定。`role` 表示本轮选号如何使用它:
| `role` | 含义 |
| --- | --- |
| `ordinary` | 普通候选。宽松模式下已有绑定也可以是普通候选 |
| `preferred` | 内置选号优先考虑,允许选择其他账号。xAI 的会话偏好由评分得出,不表示已有持久绑定 |
| `follow_only` | 委托内置选号时只跟随这个绑定账号,插件仍可显式选择其他合格候选 |
| `pinned` | 本次尝试已固定账号,例如原生续接;插件不能改选其他账号 |
关系只标在本轮可见候选上,繁忙不抹去关系,候选中没有绑定标记也不能断定是新会话。角色不授予账号资格,不代表已取得租约
- `Pick { account_id }` 显式选号,只能指定 `available: true` 的候选
- `Delegate` 将完整候选交给宿主现有调度
- `DelegateFiltered { exclude_account_ids }` 排除列出的候选,再委托内置权重、Smart 评分和亲和选择;仅接受本次候选 ID,重复 ID 合并,空列表等同于 `Delegate`
@@ -54,7 +54,7 @@ RPC v7 的帧布局、编码与会话生命周期见[通信边界](../README.md#
| 能力 | 当前版本 |
| --- | --- |
| `middleware` | `6` |
| `scheduler` | `3` |
| `scheduler` | `4` |
| `upstream_adapter` | `5` |
| `frontend_authentication`、`model_router`、`retry_policy`、`observer`、`management` | `2` |
| `model_catalog` | `2` |
@@ -72,11 +72,23 @@ pub enum ModelRouteDecision {
Reject,
}
/// 宿主在本轮调度中赋予候选的角色,与实时容量和已有会话绑定分开
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum AccountScheduleRole {
Ordinary,
Preferred,
FollowOnly,
Pinned,
}
/// 候选账号的即时调度指标;凭据和账号资料通过宿主账号接口读取
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct AccountScheduleCandidate {
pub account_id: String,
pub session_bound: bool,
pub role: AccountScheduleRole,
/// false 表示仅可等待,仍可被过滤,但不能作为本轮 Pick 的结果
pub available: bool,
pub weight: u16,
@@ -33,7 +33,7 @@ impl Capability {
| Self::RetryPolicy
| Self::Observer
| Self::Management => &[2],
Self::Scheduler => &[3],
Self::Scheduler => &[4],
Self::UpstreamAdapter => &[5],
Self::CommandLine | Self::Maintenance => &[1],
}
@@ -1,8 +1,8 @@
//! 验证插件路由和账号调度决策的类型合同与附加字段透传边界
use gateway_plugin_sdk::call::policy::{
AccountScheduleCandidate, AccountScheduleDecision, AccountScheduleRequest, ModelRouteDecision,
ModelRouteRequest, PolicyHeader,
AccountScheduleCandidate, AccountScheduleDecision, AccountScheduleRequest, AccountScheduleRole,
ModelRouteDecision, ModelRouteRequest, PolicyHeader,
};
use serde_json::json;
@@ -49,6 +49,8 @@ fn route_and_scheduler_decisions_ignore_unused_fields() {
model: Some("gpt-5".into()),
candidates: vec![AccountScheduleCandidate {
account_id: "acct_candidate".into(),
session_bound: true,
role: AccountScheduleRole::Preferred,
available: true,
weight: 10,
in_flight: 1,
@@ -136,7 +136,7 @@ fn capability_contract_versions_are_checked_independently_of_rpc_version() {
(Capability::Middleware, Stage::Request, 6, true),
(Capability::Management, Stage::Management, 2, false),
(Capability::UpstreamAdapter, Stage::Upstream, 5, true),
(Capability::Scheduler, Stage::Scheduling, 3, false),
(Capability::Scheduler, Stage::Scheduling, 4, false),
(Capability::ModelCatalog, Stage::Registration, 2, false),
] {
for mut manifest in [source_manifest(), packaged_manifest()] {
@@ -286,7 +286,7 @@ fn contribution_ids_are_owned_unique_and_stage_bounded() {
Capability::Scheduler,
ContributionDeclaration {
id: "9acme.request-tags.scheduler".into(),
version: 3,
version: 4,
stages: vec![Stage::Scheduling],
input_formats: Vec::new(),
output_formats: Vec::new(),
@@ -19,7 +19,10 @@ use gateway_core::account::{
use gateway_core::concurrency::{
CapacityWait, ConcurrencyQueuePolicy, ConcurrencyWaitQueue, QueueRejection, WaitPriority,
};
use gateway_core::engine::{AttemptContext, ContinuationAttempt, policy::AccountPolicyError};
use gateway_core::engine::{
AttemptContext, ContinuationAttempt,
policy::{AccountPolicyError, AccountScheduleOwnership},
};
use gateway_core::provider_ports::{
ProviderAccountAdmission, ProviderConcurrencyPool, ProviderCooldownPort, ProviderCooldownScope,
ProviderLeaseAcquisition, ProviderLeaseGuard, ProviderLeasePort, ProviderLeaseRequest,
@@ -1185,6 +1188,14 @@ impl CodexCredentialSelector {
model.model(),
&candidates,
&mut context,
AccountScheduleOwnership {
bound_account: binding
.as_ref()
.filter(|_| !cache_preference)
.map(ProviderSessionBinding::account_id),
follow_only,
pinned_account: pinned_account.as_ref(),
},
)
.await
{
@@ -1,6 +1,7 @@
//! 验证会话主账号偏好、严格绑定、最终请求身份与轮次关联
use super::*;
use gateway_core::engine::policy::AccountScheduleRole;
#[tokio::test]
async fn session_affinity_storage_tolerates_delays_but_rejects_expired_requests_before_sending() {
@@ -859,6 +860,7 @@ async fn child_queue_timeout_does_not_rebind_or_allow_provider_fallback() {
#[derive(Debug)]
struct SessionScheduler {
expected_owner: (bool, AccountScheduleRole),
decision: gateway_core::engine::policy::AccountScheduleDecision,
}
impl gateway_core::engine::policy::RequestPolicyPlan for SessionScheduler {
@@ -884,12 +886,17 @@ impl gateway_core::engine::policy::RequestPolicyPlan for SessionScheduler {
gateway_core::engine::policy::RequestPolicyFault,
>,
> {
assert!(
input
for (id, (bound, role)) in [
("acct_subagent_a", self.expected_owner),
("acct_subagent_b", (false, AccountScheduleRole::Ordinary)),
] {
let candidate = input
.candidates()
.iter()
.any(|candidate| candidate.account_id().as_str() == "acct_subagent_b")
);
.find(|candidate| candidate.account_id().as_str() == id)
.unwrap();
assert_eq!((candidate.session_bound(), candidate.role()), (bound, role));
}
let decision = self.decision.clone();
Box::pin(async move { Ok(decision) })
}
@@ -902,15 +909,20 @@ impl gateway_core::routing::extensions::ExtensionSetLease for SessionExtensionLe
}
#[tokio::test]
async fn child_binding_respects_filtered_delegation_and_explicit_plugin_choices() {
async fn scheduler_distinguishes_session_bindings_from_cache_preferences_and_keeps_native_selection()
{
use AccountScheduleRole::{FollowOnly, Ordinary, Preferred};
use gateway_core::account::AccountAffinity;
use gateway_core::engine::policy::RequestPolicyContext;
use gateway_core::routing::extensions::{ExtensionSetId, ExtensionSetReference};
for (choice, mode) in [
("delegate", AccountAffinity::Strict),
("pick", AccountAffinity::Strict),
("filter", AccountAffinity::Strict),
("filter", AccountAffinity::Preferred),
for (choice, mode, expected_owner) in [
("delegate", AccountAffinity::Strict, (true, FollowOnly)),
("pick", AccountAffinity::Strict, (true, FollowOnly)),
("filter", AccountAffinity::Strict, (true, FollowOnly)),
("filter", AccountAffinity::Preferred, (true, Preferred)),
("filter", AccountAffinity::Relaxed, (true, Ordinary)),
("cache", AccountAffinity::Preferred, (false, Preferred)),
("new", AccountAffinity::Preferred, (false, Ordinary)),
] {
let store = Arc::new(MemoryAccountStore::default());
create_account(&store, "acct_subagent_a").await;
@@ -923,11 +935,27 @@ async fn child_binding_respects_filtered_delegation_and_explicit_plugin_choices(
server.uri(),
leases.clone(),
);
let cache_request = || {
let payload = ProtocolPayload::json_object(
"openai",
json!({"prompt_cache_key": "shared", "input": "hello"})
.as_object()
.unwrap()
.clone(),
)
.unwrap();
Operation::Generate(GenerateRequest::from_protocol_payload(payload))
};
let seed = if choice == "cache" {
cache_request()
} else {
turn_request("root", "root-turn")
};
drop(
provider
.clone()
.execute(
planned_request("openai", turn_request("root", "root-turn")),
planned_request("openai", seed),
context("req_plugin_root", CancellationToken::new()),
)
.await
@@ -943,11 +971,12 @@ async fn child_binding_respects_filtered_delegation_and_explicit_plugin_choices(
let key = ClientApiKeyId::new("key_openai_contract").unwrap();
let policy = RequestPolicyContext::new(
Arc::new(SessionScheduler {
expected_owner,
decision: match choice {
"pick" => gateway_core::engine::policy::AccountScheduleDecision::Pick(
ProviderAccountId::new("acct_subagent_b").unwrap(),
),
"filter" => {
"filter" | "cache" | "new" => {
gateway_core::engine::policy::AccountScheduleDecision::DelegateFiltered(
BTreeSet::from([ProviderAccountId::new("acct_subagent_a").unwrap()]),
)
@@ -976,7 +1005,15 @@ async fn child_binding_respects_filtered_delegation_and_explicit_plugin_choices(
let mut pending = Box::pin(provider.clone().execute(
planned_request(
"openai",
Operation::Generate(generate_with_session_context("root", Some("child"), None)),
match choice {
"cache" => cache_request(),
"new" => turn_request("separate-session", "separate-turn"),
_ => Operation::Generate(generate_with_session_context(
"root",
Some("child"),
None,
)),
},
),
attempt,
));
@@ -991,7 +1028,7 @@ async fn child_binding_respects_filtered_delegation_and_explicit_plugin_choices(
error.send_state(),
gateway_core::upstream::UpstreamSendState::NotSent
);
} else if choice == "pick" || choice == "filter" {
} else if choice != "delegate" {
let stream = timeout(Duration::from_secs(2), pending)
.await
.unwrap()
@@ -11,7 +11,7 @@ use gateway_core::account::{
QuotaEvidence, QuotaState,
};
use gateway_core::concurrency::{CapacityWait, ConcurrencyQueuePolicy, ConcurrencyWaitQueue};
use gateway_core::engine::policy::AccountPolicyError;
use gateway_core::engine::policy::{AccountPolicyError, AccountScheduleOwnership};
use gateway_core::provider_ports::{
ProviderCooldown, ProviderCooldownPort, ProviderCooldownScope, ProviderLeaseAcquisition,
ProviderLeasePort, ProviderLeaseRequest, ProviderSchedulingLeaseRequest,
@@ -325,6 +325,10 @@ impl GrokAccountSessionSelector {
Some(request.upstream_model().as_str()),
&candidates,
&mut context,
AccountScheduleOwnership {
pinned_account: request.required_account(),
..Default::default()
},
)
.await
}
@@ -334,7 +334,16 @@ async fn filtered_scheduling_covers_lease_retry_waiting_and_pinned_terminal_reje
assert!(leases.acquired.lock().unwrap().is_empty());
assert_eq!(transport.calls.load(Ordering::SeqCst), 0);
if mode == "pin" {
assert_eq!(seen.lock().unwrap()[0].candidates().len(), 1);
let seen = seen.lock().unwrap();
let [owner] = seen[0].candidates() else {
panic!("native continuation must have one visible owner");
};
assert_eq!(owner.account_id(), &account_id("filter-a"));
assert_eq!(
owner.role(),
gateway_core::engine::policy::AccountScheduleRole::Pinned
);
assert!(!owner.session_bound());
}
} else {
let stream = result.expect("allowed account");