kiss_workflow/runner.rs
1//! The boundary between a workflow script and real agents.
2//!
3//! This crate never starts an agent itself. It hands a request to an
4//! [`AgentRunner`] the host supplies. Tests supply a fake runner, so the whole
5//! language is exercised without a model.
6
7use serde_json::Value as Json;
8use tokio_util::sync::CancellationToken;
9
10/// Identifies one `agent()` call site by its position in the run.
11///
12/// Because the interpreter is deterministic, the same script with the same
13/// arguments issues the same sequence of calls.
14pub type AgentId = u32;
15
16/// One child agent to start.
17#[derive(Debug, Clone, PartialEq)]
18pub struct AgentRequest {
19 /// Position of this `agent()` call in the run, counting from zero.
20 pub index: AgentId,
21 pub prompt: String,
22 /// Display name for the progress view. Falls back to the phase and index.
23 pub label: Option<String>,
24 pub phase: String,
25 /// A model pattern for the host to resolve, such as `sonnet` or
26 /// `anthropic/claude-sonnet-5`.
27 pub model: Option<String>,
28 /// A thinking level name, such as `low` or `high`.
29 pub effort: Option<String>,
30 /// A JSON Schema the answer must satisfy. When set, the call returns parsed
31 /// data instead of text.
32 pub schema: Option<Json>,
33 pub timeout_ms: Option<u64>,
34}
35
36/// How one child agent ended.
37#[derive(Debug, Clone, PartialEq)]
38pub enum AgentOutcome {
39 /// The agent answered. The value is text unless the request carried a
40 /// schema, in which case it is the parsed structured answer.
41 Done(Json),
42 /// The user stopped this agent, or the whole run.
43 Stopped,
44 /// The agent failed after any retries the host applied.
45 Failed(String),
46}
47
48/// Starts one child agent and waits for its answer.
49#[async_trait::async_trait]
50pub trait AgentRunner: Send + Sync + 'static {
51 async fn run_agent(&self, request: AgentRequest, cancel: CancellationToken) -> AgentOutcome;
52
53 /// Tokens this agent used, for the progress view. Hosts that do not track
54 /// usage may leave this at zero.
55 fn tokens_used(&self, _index: AgentId) -> u64 {
56 0
57 }
58}
59
60/// Bounds on one run.
61#[derive(Debug, Clone, Copy, PartialEq, Eq)]
62pub struct Limits {
63 /// Agents running at once.
64 pub max_concurrency: usize,
65 /// Agents started over the whole run, which bounds the cost of a runaway
66 /// script.
67 pub max_agents: u32,
68 /// Items one `parallel()` or `pipeline()` call may accept. A longer list is
69 /// an error rather than a silent truncation, because dropping part of the
70 /// work without saying so is worse than refusing it.
71 pub max_fanout: usize,
72 /// Interpreter steps, which stops a loop that never terminates.
73 pub max_steps: u64,
74}
75
76/// The most child agents running at once that the runtime allows.
77const MAX_CONCURRENCY: usize = 16;
78/// The most child agents one run may start, and the default.
79const MAX_AGENTS: u32 = 1000;
80/// The largest list one `parallel` or `pipeline` call may fan out over.
81const MAX_FANOUT: usize = 4096;
82
83impl Default for Limits {
84 fn default() -> Self {
85 Limits {
86 max_concurrency: default_concurrency(),
87 max_agents: MAX_AGENTS,
88 max_fanout: MAX_FANOUT,
89 max_steps: 50_000_000,
90 }
91 }
92}
93
94/// The most at once, or fewer on a machine or container with fewer cores.
95fn default_concurrency() -> usize {
96 let cores = std::thread::available_parallelism()
97 .map(|count| count.get())
98 .unwrap_or(4);
99 cores.clamp(2, MAX_CONCURRENCY)
100}
101
102impl Limits {
103 /// Clamp caller-supplied limits into a range the runtime can honor.
104 pub fn sanitized(mut self) -> Limits {
105 self.max_concurrency = self.max_concurrency.clamp(1, MAX_CONCURRENCY);
106 self.max_agents = self.max_agents.clamp(1, MAX_AGENTS);
107 self.max_fanout = self.max_fanout.clamp(1, MAX_FANOUT);
108 self.max_steps = self.max_steps.max(1000);
109 self
110 }
111}
112
113#[cfg(test)]
114mod tests {
115 use super::*;
116
117 #[test]
118 fn limits_are_clamped_into_a_range_the_runtime_can_honor() {
119 let limits = Limits {
120 max_concurrency: 500,
121 max_agents: 100_000,
122 max_fanout: usize::MAX,
123 max_steps: 1,
124 }
125 .sanitized();
126 assert_eq!(limits.max_concurrency, 16);
127 assert_eq!(limits.max_agents, 1000);
128 assert_eq!(limits.max_fanout, 4096);
129 assert_eq!(limits.max_steps, 1000);
130 }
131
132 #[test]
133 fn the_default_concurrency_stays_within_bounds() {
134 let limits = Limits::default();
135 assert!((2..=16).contains(&limits.max_concurrency));
136 }
137}