1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
use tea_protocol::ToolCallId;
use tea_tools::{SchedulerClass, ValidatedToolInvocation};
use crate::{KernelError, KernelErrorCode};
/// Effect-aware tool scheduler producing lane assignments only.
///
/// The scheduler never executes tools. It partitions validated invocations by
/// `SchedulerClass` so the kernel can run parallel-safe work concurrently while
/// serializing mutation and granting exclusive work its own lane. Source order
/// within a lane is preserved; the kernel commits results in canonical source
/// order regardless of completion order.
#[derive(Debug, Clone, Copy, Default)]
pub struct Scheduler;
/// One scheduler lane containing invocations that share an execution rule.
#[derive(Debug, Clone)]
pub struct Lane<'a> {
pub(crate) class: SchedulerClass,
pub(crate) invocations: Vec<&'a ValidatedToolInvocation>,
}
impl<'a> Lane<'a> {
/// Returns the lane's scheduler class.
#[must_use]
pub const fn class(&self) -> SchedulerClass {
self.class
}
/// Returns the invocations assigned to this lane in source order.
#[must_use]
pub fn invocations(&self) -> &[&'a ValidatedToolInvocation] {
&self.invocations
}
/// Returns whether invocations in this lane may execute concurrently.
#[must_use]
pub fn allows_parallel(&self) -> bool {
self.class.allows_parallel_execution()
}
}
/// Immutable plan of lane assignments for one model turn.
#[derive(Debug, Clone)]
pub struct SchedulePlan<'a> {
lanes: Vec<Lane<'a>>,
source_order: Vec<ToolCallId>,
}
impl<'a> SchedulePlan<'a> {
/// Returns the assigned lanes.
#[must_use]
pub fn lanes(&self) -> &[Lane<'a>] {
&self.lanes
}
/// Returns the count of scheduled invocations.
#[must_use]
pub fn len(&self) -> usize {
self.source_order.len()
}
/// Returns whether the plan scheduled no invocations.
#[must_use]
pub fn is_empty(&self) -> bool {
self.source_order.is_empty()
}
/// Returns the canonical source-order tool-call identifiers.
#[must_use]
pub fn source_order(&self) -> &[ToolCallId] {
&self.source_order
}
}
impl Scheduler {
/// Partitions validated invocations into scheduler lanes.
///
/// # Errors
///
/// Returns a `SchedulerConflict` for any invocation whose
/// `SchedulerClass::requires_policy()` is true (unknown effects). The
/// scheduler never auto-schedules policy-required work.
pub fn plan<'a>(
&self,
invocations: &'a [&'a ValidatedToolInvocation],
) -> Result<SchedulePlan<'a>, KernelError> {
if invocations
.iter()
.any(|invocation| invocation.scheduler_class().requires_policy())
{
return Err(KernelError::new(
KernelErrorCode::SchedulerConflict,
"tool invocation requires policy before scheduling",
));
}
let source_order = invocations
.iter()
.map(|invocation| *invocation.tool_call_id())
.collect();
let mut parallel: Vec<&ValidatedToolInvocation> = Vec::new();
let mut serial: Vec<&ValidatedToolInvocation> = Vec::new();
let mut exclusive: Vec<&ValidatedToolInvocation> = Vec::new();
for invocation in invocations {
match invocation.scheduler_class() {
SchedulerClass::ParallelReadOnly | SchedulerClass::ParallelRetrySafe => {
parallel.push(invocation);
}
SchedulerClass::Serial => serial.push(invocation),
SchedulerClass::Exclusive => exclusive.push(invocation),
SchedulerClass::PolicyRequired => {
return Err(KernelError::new(
KernelErrorCode::SchedulerConflict,
"tool invocation requires policy before scheduling",
));
}
}
}
let mut lanes = Vec::new();
if !parallel.is_empty() {
lanes.push(Lane {
class: SchedulerClass::ParallelReadOnly,
invocations: parallel,
});
}
if !serial.is_empty() {
lanes.push(Lane {
class: SchedulerClass::Serial,
invocations: serial,
});
}
for invocation in exclusive {
lanes.push(Lane {
class: SchedulerClass::Exclusive,
invocations: vec![invocation],
});
}
Ok(SchedulePlan {
lanes,
source_order,
})
}
}