Vakyartha documentation

1//! The per-turn tool surface: which admitted tools are *loaded* (full schema
2//! in the request) and which are *deferred* (named in the prompt's catalogue,
3//! schema one `find_tools` call away). See docs/design/68-context-engine.md §5.
4//!
5//! This is presentation, never policy. Every tool here was already admitted
6//! by [`super::turn`]; the split only decides what the model reads up front.
7//! A wrong prediction therefore costs one `find_tools` round trip and is the
8//! measured misread (`crate::misread`), never a missing capability.
9//!
10//! The split reads each tool's own declaration (`Tool::always_loaded`,
11//! `Tool::serves`, `Tool::presents_cards`) — the harness keeps no table of
12//! tool names.
13
14use std::collections::BTreeSet;
15use std::sync::Arc;
16
17use vak_llm::ToolDefinition;
18
19use super::domain::{Domain, Serves};
20
21/// One turn's tools, split for the request.
22#[derive(Debug, Clone, Default)]
23pub struct ToolSurface {
24 /// Sent with full schemas.
25 pub core: Vec<ToolDefinition>,
26 /// Schema withheld; reachable through `find_tools`, or Anthropic
27 /// `defer_loading` on legs that support it.
28 pub deferred: Vec<ToolDefinition>,
29 /// Deferred because the turn's reading did not predict them — the set a
30 /// later call measures a misread against. Card tools are excluded: a
31 /// card is an output choice, not a reading of what the request needs.
32 pub unpredicted: BTreeSet<String>,
33}
34
35/// Split the admitted `tools` for one turn.
36///
37/// * `required_domains` is the reading's prediction. `All` (progressive
38/// disclosure off, or the kernel disabled) loads everything.
39/// * `predicted_cards` names the card tools the request itself reads as
40/// (`presentation_tools::predicted_card_tools`); other card tools defer.
41///
42/// Always-loaded and undeclared tools are loaded whatever the prediction:
43/// the first because the model cannot operate without them, the second
44/// because deferring is a context saving and an unknown tool fails open.
45pub fn build_tool_surface(
46 tools: &[Arc<dyn vak_tools::Tool>],
47 required_domains: &vak_intent::DomainSet,
48 predicted_cards: &BTreeSet<String>,
49) -> ToolSurface {
50 let required: Option<BTreeSet<Domain>> = (!required_domains.is_unconstrained())
51 .then(|| required_domains.iter().map(|d| Domain::parse(d)).collect());
52 let mut surface = ToolSurface::default();
53 for tool in tools {
54 let definition = ToolDefinition::new(tool.name(), tool.description(), tool.schema());
55 let loaded = match &required {
56 None => true,
57 Some(_) if tool.always_loaded() => true,
58 Some(_) if tool.presents_cards() => predicted_cards.contains(tool.name()),
59 Some(required) => Serves::from_labels(tool.serves()).serves_any(required),
60 };
61 if loaded {
62 surface.core.push(definition);
63 } else {
64 if !tool.presents_cards() {
65 surface.unpredicted.insert(tool.name().to_string());
66 }
67 surface.deferred.push(definition);
68 }
69 }
70 surface
71}
72
73/// The prompt's catalogue of the admitted tools that are not always loaded:
74/// one line each, name and first sentence, no schema. `entries` are
75/// `(name, description)` pairs. It depends only on what is admitted — never
76/// on the turn's reading — so it stays byte-stable in the cached prefix while
77/// the loaded set moves. Empty when nothing can defer.
78pub fn tool_catalogue<'a>(entries: impl IntoIterator<Item = (&'a str, &'a str)>) -> String {
79 let mut lines: Vec<String> = entries
80 .into_iter()
81 .map(|(name, description)| format!("- {name} — {}", first_sentence(description)))
82 .collect();
83 if lines.is_empty() {
84 return String::new();
85 }
86 lines.sort();
87 format!(
88 "\nMore tools (a tool not in your schemas this turn is loaded by calling `find_tools` with its name or purpose; call it before using one):\n{}\n",
89 lines.join("\n")
90 )
91}
92
93fn first_sentence(description: &str) -> &str {
94 let trimmed = description.trim();
95 if let Some(idx) = trimmed.find(". ") {
96 return &trimmed[..=idx];
97 }
98 trimmed.lines().next().unwrap_or(trimmed)
99}
100
101#[cfg(test)]
102#[allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
103mod tests {
104 use super::*;
105 use serde_json::Value;
106
107 struct Fake {
108 name: &'static str,
109 serves: &'static [&'static str],
110 always: bool,
111 card: bool,
112 }
113
114 #[async_trait::async_trait]
115 impl vak_tools::Tool for Fake {
116 fn name(&self) -> &str {
117 self.name
118 }
119 fn description(&self) -> &str {
120 "Does a thing. Then more detail nobody needs up front."
121 }
122 fn schema(&self) -> Value {
123 serde_json::json!({"type": "object"})
124 }
125 async fn execute(&self, _: &Value, _: &vak_tools::ToolContext) -> vak_tools::ToolOutput {
126 vak_tools::ToolOutput::ok("")
127 }
128 fn serves(&self) -> &'static [&'static str] {
129 self.serves
130 }
131 fn always_loaded(&self) -> bool {
132 self.always
133 }
134 fn presents_cards(&self) -> bool {
135 self.card
136 }
137 }
138
139 fn tool(name: &'static str, serves: &'static [&'static str]) -> Arc<dyn vak_tools::Tool> {
140 Arc::new(Fake {
141 name,
142 serves,
143 always: false,
144 card: false,
145 })
146 }
147
148 fn fixture() -> Vec<Arc<dyn vak_tools::Tool>> {
149 vec![
150 Arc::new(Fake {
151 name: "read",
152 serves: &["filesystem"],
153 always: true,
154 card: false,
155 }),
156 tool("bash", &["code-exec"]),
157 tool("webfetch", &["web", "live-data"]),
158 tool("plugin_thing", &[]),
159 Arc::new(Fake {
160 name: "emit_chart_card",
161 serves: &[],
162 always: false,
163 card: true,
164 }),
165 ]
166 }
167
168 fn names(defs: &[ToolDefinition]) -> Vec<&str> {
169 defs.iter().map(|d| d.name.as_str()).collect()
170 }
171
172 #[test]
173 fn unconstrained_domains_load_everything() {
174 let surface = build_tool_surface(&fixture(), &vak_intent::DomainSet::All, &BTreeSet::new());
175 assert_eq!(surface.core.len(), 5);
176 assert!(surface.deferred.is_empty());
177 assert!(surface.unpredicted.is_empty());
178 }
179
180 #[test]
181 fn a_reading_loads_what_it_predicts_and_defers_the_rest() {
182 let surface = build_tool_surface(
183 &fixture(),
184 &vak_intent::DomainSet::only(["web"]),
185 &BTreeSet::new(),
186 );
187 assert_eq!(
188 names(&surface.core),
189 vec!["read", "webfetch", "plugin_thing"]
190 );
191 assert_eq!(names(&surface.deferred), vec!["bash", "emit_chart_card"]);
192 assert_eq!(
193 surface.unpredicted,
194 BTreeSet::from(["bash".to_string()]),
195 "a deferred card is an output choice, not a misread"
196 );
197 }
198
199 #[test]
200 fn a_predicted_card_tool_is_loaded() {
201 let surface = build_tool_surface(
202 &fixture(),
203 &vak_intent::DomainSet::Empty,
204 &BTreeSet::from(["emit_chart_card".to_string()]),
205 );
206 assert!(names(&surface.core).contains(&"emit_chart_card"));
207 }
208
209 /// The catalogue is a function of the admitted tools only, so the cached
210 /// prefix does not move when the reading does.
211 #[test]
212 fn the_catalogue_is_stable_sorted_and_schema_free() {
213 let entries = [
214 (
215 "webfetch",
216 "Fetch a URL. Long detail nobody needs up front.",
217 ),
218 ("bash", "Run a command."),
219 ];
220 let catalogue = tool_catalogue(entries);
221 let mut reversed = entries;
222 reversed.reverse();
223 assert_eq!(catalogue, tool_catalogue(reversed));
224 assert!(catalogue.contains("- bash — Run a command.\n- webfetch — Fetch a URL.\n"));
225 assert!(!catalogue.contains("nobody needs"));
226 assert!(tool_catalogue([]).is_empty());
227 }
228}
229

1//! The per-turn tool surface: which admitted tools are *loaded* (full schema
2//! in the request) and which are *deferred* (named in the prompt's catalogue,
3//! schema one `find_tools` call away). See docs/design/68-context-engine.md §5.
4//!
5//! This is presentation, never policy. Every tool here was already admitted
6//! by [`super::turn`]; the split only decides what the model reads up front.
7//! A wrong prediction therefore costs one `find_tools` round trip and is the
8//! measured misread (`crate::misread`), never a missing capability.
9//!
10//! The split reads each tool's own declaration (`Tool::always_loaded`,
11//! `Tool::serves`, `Tool::presents_cards`) — the harness keeps no table of
12//! tool names.
13
14use std::collections::BTreeSet;
15use std::sync::Arc;
16
17use vak_llm::ToolDefinition;
18
19use super::domain::{Domain, Serves};
20
21/// One turn's tools, split for the request.
22#[derive(Debug, Clone, Default)]
23pub struct ToolSurface {
24 /// Sent with full schemas.
25 pub core: Vec<ToolDefinition>,
26 /// Schema withheld; reachable through `find_tools`, or Anthropic
27 /// `defer_loading` on legs that support it.
28 pub deferred: Vec<ToolDefinition>,
29 /// Deferred because the turn's reading did not predict them — the set a
30 /// later call measures a misread against. Card tools are excluded: a
31 /// card is an output choice, not a reading of what the request needs.
32 pub unpredicted: BTreeSet<String>,
33}
34
35/// Split the admitted `tools` for one turn.
36///
37/// * `required_domains` is the reading's prediction. `All` (progressive
38/// disclosure off, or the kernel disabled) loads everything.
39/// * `predicted_cards` names the card tools the request itself reads as
40/// (`presentation_tools::predicted_card_tools`); other card tools defer.
41///
42/// Always-loaded and undeclared tools are loaded whatever the prediction:
43/// the first because the model cannot operate without them, the second
44/// because deferring is a context saving and an unknown tool fails open.
45pub fn build_tool_surface(
46 tools: &[Arc<dyn vak_tools::Tool>],
47 required_domains: &vak_intent::DomainSet,
48 predicted_cards: &BTreeSet<String>,
49) -> ToolSurface {
50 let required: Option<BTreeSet<Domain>> = (!required_domains.is_unconstrained())
51 .then(|| required_domains.iter().map(|d| Domain::parse(d)).collect());
52 let mut surface = ToolSurface::default();
53 for tool in tools {
54 let definition = ToolDefinition::new(tool.name(), tool.description(), tool.schema());
55 let loaded = match &required {
56 None => true,
57 Some(_) if tool.always_loaded() => true,
58 Some(_) if tool.presents_cards() => predicted_cards.contains(tool.name()),
59 Some(required) => Serves::from_labels(tool.serves()).serves_any(required),
60 };
61 if loaded {
62 surface.core.push(definition);
63 } else {
64 if !tool.presents_cards() {
65 surface.unpredicted.insert(tool.name().to_string());
66 }
67 surface.deferred.push(definition);
68 }
69 }
70 surface
71}
72
73/// The prompt's catalogue of the admitted tools that are not always loaded:
74/// one line each, name and first sentence, no schema. `entries` are
75/// `(name, description)` pairs. It depends only on what is admitted — never
76/// on the turn's reading — so it stays byte-stable in the cached prefix while
77/// the loaded set moves. Empty when nothing can defer.
78pub fn tool_catalogue<'a>(entries: impl IntoIterator<Item = (&'a str, &'a str)>) -> String {
79 let mut lines: Vec<String> = entries
80 .into_iter()
81 .map(|(name, description)| format!("- {name} — {}", first_sentence(description)))
82 .collect();
83 if lines.is_empty() {
84 return String::new();
85 }
86 lines.sort();
87 format!(
88 "\nMore tools (a tool not in your schemas this turn is loaded by calling `find_tools` with its name or purpose; call it before using one):\n{}\n",
89 lines.join("\n")
90 )
91}
92
93fn first_sentence(description: &str) -> &str {
94 let trimmed = description.trim();
95 if let Some(idx) = trimmed.find(". ") {
96 return &trimmed[..=idx];
97 }
98 trimmed.lines().next().unwrap_or(trimmed)
99}
100
101#[cfg(test)]
102#[allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
103mod tests {
104 use super::*;
105 use serde_json::Value;
106
107 struct Fake {
108 name: &'static str,
109 serves: &'static [&'static str],
110 always: bool,
111 card: bool,
112 }
113
114 #[async_trait::async_trait]
115 impl vak_tools::Tool for Fake {
116 fn name(&self) -> &str {
117 self.name
118 }
119 fn description(&self) -> &str {
120 "Does a thing. Then more detail nobody needs up front."
121 }
122 fn schema(&self) -> Value {
123 serde_json::json!({"type": "object"})
124 }
125 async fn execute(&self, _: &Value, _: &vak_tools::ToolContext) -> vak_tools::ToolOutput {
126 vak_tools::ToolOutput::ok("")
127 }
128 fn serves(&self) -> &'static [&'static str] {
129 self.serves
130 }
131 fn always_loaded(&self) -> bool {
132 self.always
133 }
134 fn presents_cards(&self) -> bool {
135 self.card
136 }
137 }
138
139 fn tool(name: &'static str, serves: &'static [&'static str]) -> Arc<dyn vak_tools::Tool> {
140 Arc::new(Fake {
141 name,
142 serves,
143 always: false,
144 card: false,
145 })
146 }
147
148 fn fixture() -> Vec<Arc<dyn vak_tools::Tool>> {
149 vec![
150 Arc::new(Fake {
151 name: "read",
152 serves: &["filesystem"],
153 always: true,
154 card: false,
155 }),
156 tool("bash", &["code-exec"]),
157 tool("webfetch", &["web", "live-data"]),
158 tool("plugin_thing", &[]),
159 Arc::new(Fake {
160 name: "emit_chart_card",
161 serves: &[],
162 always: false,
163 card: true,
164 }),
165 ]
166 }
167
168 fn names(defs: &[ToolDefinition]) -> Vec<&str> {
169 defs.iter().map(|d| d.name.as_str()).collect()
170 }
171
172 #[test]
173 fn unconstrained_domains_load_everything() {
174 let surface = build_tool_surface(&fixture(), &vak_intent::DomainSet::All, &BTreeSet::new());
175 assert_eq!(surface.core.len(), 5);
176 assert!(surface.deferred.is_empty());
177 assert!(surface.unpredicted.is_empty());
178 }
179
180 #[test]
181 fn a_reading_loads_what_it_predicts_and_defers_the_rest() {
182 let surface = build_tool_surface(
183 &fixture(),
184 &vak_intent::DomainSet::only(["web"]),
185 &BTreeSet::new(),
186 );
187 assert_eq!(
188 names(&surface.core),
189 vec!["read", "webfetch", "plugin_thing"]
190 );
191 assert_eq!(names(&surface.deferred), vec!["bash", "emit_chart_card"]);
192 assert_eq!(
193 surface.unpredicted,
194 BTreeSet::from(["bash".to_string()]),
195 "a deferred card is an output choice, not a misread"
196 );
197 }
198
199 #[test]
200 fn a_predicted_card_tool_is_loaded() {
201 let surface = build_tool_surface(
202 &fixture(),
203 &vak_intent::DomainSet::Empty,
204 &BTreeSet::from(["emit_chart_card".to_string()]),
205 );
206 assert!(names(&surface.core).contains(&"emit_chart_card"));
207 }
208
209 /// The catalogue is a function of the admitted tools only, so the cached
210 /// prefix does not move when the reading does.
211 #[test]
212 fn the_catalogue_is_stable_sorted_and_schema_free() {
213 let entries = [
214 (
215 "webfetch",
216 "Fetch a URL. Long detail nobody needs up front.",
217 ),
218 ("bash", "Run a command."),
219 ];
220 let catalogue = tool_catalogue(entries);
221 let mut reversed = entries;
222 reversed.reverse();
223 assert_eq!(catalogue, tool_catalogue(reversed));
224 assert!(catalogue.contains("- bash — Run a command.\n- webfetch — Fetch a URL.\n"));
225 assert!(!catalogue.contains("nobody needs"));
226 assert!(tool_catalogue([]).is_empty());
227 }
228}
229

Indexing the workspace…