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
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
//! [`RunOptions`] and its defaults / `Debug` impl.
use crate::guardrail::Guardrail;
use std::sync::Arc;
/// Default cap on the total bytes a streaming run will forward to the
/// caller before aborting. Sized at 4 MiB — comfortably above any sane
/// chat response while small enough to bound a runaway provider.
const DEFAULT_MAX_RESPONSE_BYTES: usize = 4 * 1024 * 1024;
/// Tunables for [`super::run_steps`] and [`super::run_steps_streaming`].
#[derive(Clone)]
#[non_exhaustive]
pub struct RunOptions {
/// Maximum number of (LLM call + tool dispatch) iterations.
pub max_steps: u32,
/// Maximum tokens of short-term memory to load into the prompt.
pub max_history_tokens: usize,
/// Cap on bytes accumulated across a single streaming cycle's
/// content + serialised tool-call payloads. Exceeding this aborts
/// the run with a terminal `Err`. Applies only to
/// [`super::run_steps_streaming`]; [`super::run_steps`] is
/// unaffected (the non-streaming path inherits the provider's own
/// limits).
pub max_response_bytes: usize,
/// Pre/post-LLM validators consulted around every LLM call.
///
/// Empty by default — existing callers see no behavioural change.
/// Each guardrail is invoked in registration order; the first
/// non-[`GuardrailOutcome::Pass`](crate::guardrail::GuardrailOutcome::Pass)
/// outcome short-circuits the run with
/// [`Error::Refused`](crate::error::Error::Refused) or
/// [`Error::Handoff`](crate::error::Error::Handoff). In
/// [`super::run_steps_streaming`], post-LLM guardrails see the
/// buffered assistant message at the end of each cycle, and a
/// non-`Pass` outcome propagates as a terminal
/// `LlmError::Server("refused: …")` or `"handoff to <agent>: …"`
/// chunk.
pub guardrails: Vec<Arc<dyn Guardrail>>,
/// Per-step review policy consulted after each LLM step to decide
/// whether to pause for human approval (ADR-045). `Ok(None)` from
/// the policy proceeds; `Ok(Some(reason))` suspends the run and
/// returns [`crate::error::Error::Suspended`]. Defaults to
/// [`super::NeverReview`], which never pauses.
pub review_policy: Arc<dyn crate::runtime::ReviewPolicy>,
/// When `Some`, suspended-run checkpoints are persisted to this
/// `KvStore` bucket so a different process can resume the run via
/// `runtime::resume_from_checkpoint`. `None` keeps the checkpoint
/// inside the returned [`crate::error::Error::Suspended`] only
/// (within-process resume).
pub checkpoint_kv_bucket: Option<String>,
/// When `Some`, the run loop records each successful LLM call to this sink
/// (ADR-048) so a replayable capture can be built. `None` (default) records
/// no LLM I/O — today's behaviour. See
/// [`CaptureSink`](crate::runtime::CaptureSink).
pub capture_sink: Option<Arc<dyn crate::runtime::CaptureSink>>,
}
impl std::fmt::Debug for RunOptions {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("RunOptions")
.field("max_steps", &self.max_steps)
.field("max_history_tokens", &self.max_history_tokens)
.field("max_response_bytes", &self.max_response_bytes)
.field("guardrails", &self.guardrails.len())
.field("checkpoint_kv_bucket", &self.checkpoint_kv_bucket)
.field("capture_sink", &self.capture_sink.is_some())
.finish_non_exhaustive()
}
}
impl RunOptions {
/// Overrides [`Self::max_steps`].
pub fn with_max_steps(mut self, steps: u32) -> Self {
self.max_steps = steps;
self
}
/// Replaces the guardrail chain; see [`Self::guardrails`] for execution semantics.
pub fn with_guardrails(mut self, guardrails: Vec<Arc<dyn Guardrail>>) -> Self {
self.guardrails = guardrails;
self
}
/// Overrides [`Self::review_policy`].
pub fn with_review_policy(mut self, policy: Arc<dyn crate::runtime::ReviewPolicy>) -> Self {
self.review_policy = policy;
self
}
/// Persists suspend checkpoints to `bucket` in the agent's `KvStore`
/// (ADR-045), enabling cross-process resume. Without this, the checkpoint
/// travels only inside the returned [`crate::error::Error::Suspended`].
pub fn with_checkpoint_bucket(mut self, bucket: impl Into<String>) -> Self {
self.checkpoint_kv_bucket = Some(bucket.into());
self
}
/// Records each successful LLM call to `sink` (ADR-048) so a replayable
/// capture can be built from a live run.
pub fn with_capture_sink(mut self, sink: Arc<dyn crate::runtime::CaptureSink>) -> Self {
self.capture_sink = Some(sink);
self
}
}
impl Default for RunOptions {
fn default() -> Self {
Self {
max_steps: 16,
max_history_tokens: 8_000,
max_response_bytes: DEFAULT_MAX_RESPONSE_BYTES,
guardrails: Vec::new(),
review_policy: Arc::new(crate::runtime::NeverReview),
checkpoint_kv_bucket: None,
capture_sink: None,
}
}
}
#[cfg(test)]
mod tests {
use super::*;
/// Pin the streaming byte cap so an accidental retune of
/// [`DEFAULT_MAX_RESPONSE_BYTES`] is caught at test time rather
/// than silently changing the runtime contract for every caller
/// using `RunOptions::default()`.
#[test]
fn default_max_response_bytes_is_four_mebibytes() {
assert_eq!(RunOptions::default().max_response_bytes, 4 * 1024 * 1024);
}
#[tokio::test]
async fn default_review_policy_never_pauses_and_no_bucket() {
let opts = RunOptions::default();
assert!(opts.checkpoint_kv_bucket.is_none());
let msg = crate::llm::Message {
role: crate::llm::Role::Assistant,
content: "hi".into(),
tool_calls: vec![],
tool_call_id: None,
};
assert_eq!(
opts.review_policy
.should_pause_for_approval(1, &msg)
.await
.unwrap(),
None
);
}
#[tokio::test]
async fn builders_set_review_fields() {
struct PauseAlways;
#[async_trait::async_trait]
impl crate::runtime::ReviewPolicy for PauseAlways {
async fn should_pause_for_approval(
&self,
_step: u32,
_message: &crate::llm::Message,
) -> Result<Option<String>, crate::error::Error> {
Ok(Some("always".into()))
}
}
let opts = RunOptions::default()
.with_checkpoint_bucket("klieo.run-checkpoints")
.with_review_policy(std::sync::Arc::new(PauseAlways));
assert_eq!(
opts.checkpoint_kv_bucket.as_deref(),
Some("klieo.run-checkpoints")
);
let msg = crate::llm::Message {
role: crate::llm::Role::Assistant,
content: "hi".into(),
tool_calls: vec![],
tool_call_id: None,
};
assert_eq!(
opts.review_policy
.should_pause_for_approval(1, &msg)
.await
.unwrap(),
Some("always".to_string()),
"with_review_policy must install the supplied policy, not the default"
);
}
}