Skip to main content

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}