1use proc_macro::TokenStream;
9use quote::{format_ident, quote};
10use syn::{
11 Attribute, FnArg, ImplItem, ItemImpl, Lit, Meta, Pat, ReturnType, Type, parse_macro_input,
12 spanned::Spanned,
13};
14
15#[proc_macro_attribute]
40pub fn tool_registry(attr: TokenStream, item: TokenStream) -> TokenStream {
41 let attr = proc_macro2::TokenStream::from(attr);
42 let impl_block = parse_macro_input!(item as ItemImpl);
43
44 expand_tool_registry(attr, impl_block)
45 .unwrap_or_else(syn::Error::into_compile_error)
46 .into()
47}
48
49fn expand_tool_registry(
50 attr: proc_macro2::TokenStream,
51 mut impl_block: ItemImpl,
52) -> syn::Result<proc_macro2::TokenStream> {
53 if !attr.is_empty() {
54 return Err(syn::Error::new(
55 attr.span(),
56 "tool_registry does not accept arguments",
57 ));
58 }
59
60 let self_ty = impl_block.self_ty.as_ref().clone();
61 let mut generated_items = Vec::new();
62
63 for item in &mut impl_block.items {
64 let ImplItem::Fn(method) = item else {
65 continue;
66 };
67
68 let tool_attrs: Vec<_> = method
69 .attrs
70 .iter()
71 .filter(|attr| attr.path().is_ident("tool"))
72 .collect();
73 if tool_attrs.len() > 1 {
74 return Err(syn::Error::new_spanned(
75 tool_attrs[1],
76 "duplicate #[tool] attribute",
77 ));
78 }
79 let Some(tool_attr) = tool_attrs.first() else {
80 continue;
81 };
82 if !matches!(tool_attr.meta, Meta::Path(_)) {
83 return Err(syn::Error::new_spanned(
84 tool_attr,
85 "#[tool] does not accept arguments",
86 ));
87 }
88
89 method.attrs.retain(|attr| !attr.path().is_ident("tool"));
90 generated_items.push(generate_tool_impl(&self_ty, method)?);
91
92 for input in &mut method.sig.inputs {
93 if let FnArg::Typed(pat_type) = input {
94 pat_type
95 .attrs
96 .retain(|attr| !attr.path().is_ident("description"));
97 }
98 }
99 }
100
101 Ok(quote! {
102 #impl_block
103
104 #(#generated_items)*
105 })
106}
107
108fn extract_doc_comment(attrs: &[Attribute]) -> String {
109 let mut lines = Vec::new();
110
111 for attr in attrs {
112 if attr.path().is_ident("doc")
113 && let Meta::NameValue(meta) = &attr.meta
114 && let syn::Expr::Lit(expr_lit) = &meta.value
115 && let Lit::Str(lit_str) = &expr_lit.lit
116 {
117 let line = lit_str.value();
118 let trimmed = line.strip_prefix(' ').unwrap_or(&line);
119 lines.push(trimmed.to_string());
120 }
121 }
122
123 lines.join("\n")
124}
125
126fn extract_description_attr(attrs: &[Attribute]) -> syn::Result<Option<String>> {
127 let mut description = None;
128
129 for attr in attrs
130 .iter()
131 .filter(|attr| attr.path().is_ident("description"))
132 {
133 let value = match &attr.meta {
134 Meta::NameValue(meta) => match &meta.value {
135 syn::Expr::Lit(expr_lit) => match &expr_lit.lit {
136 Lit::Str(value) => value.value(),
137 _ => {
138 return Err(syn::Error::new_spanned(
139 attr,
140 "description must be a string literal",
141 ));
142 }
143 },
144 _ => {
145 return Err(syn::Error::new_spanned(
146 attr,
147 "description must be a string literal",
148 ));
149 }
150 },
151 _ => {
152 return Err(syn::Error::new_spanned(
153 attr,
154 "expected #[description = \"...\"]",
155 ));
156 }
157 };
158
159 if description.replace(value).is_some() {
160 return Err(syn::Error::new_spanned(
161 attr,
162 "duplicate #[description] attribute",
163 ));
164 }
165 }
166
167 Ok(description)
168}
169
170fn argument_ident(pat: &Pat) -> syn::Result<&syn::Ident> {
171 match pat {
172 Pat::Ident(pat_ident) => Ok(&pat_ident.ident),
173 _ => Err(syn::Error::new_spanned(
174 pat,
175 "tool arguments must use simple identifier patterns",
176 )),
177 }
178}
179
180fn is_tool_execution_context_type(ty: &Type) -> bool {
181 let Type::Path(path) = ty else {
182 return false;
183 };
184 path.path
185 .segments
186 .last()
187 .is_some_and(|segment| segment.ident == "ToolExecutionContext")
188}
189
190fn generate_tool_impl(
191 self_ty: &Type,
192 method: &syn::ImplItemFn,
193) -> syn::Result<proc_macro2::TokenStream> {
194 let sig = &method.sig;
195 let method_name = &sig.ident;
196 let tool_name = method_name.to_string();
197
198 let pascal_name = to_pascal_case(&method_name.to_string());
199 let tool_struct_name = format_ident!("Tool{}", pascal_name);
200 let args_struct_name = format_ident!("{}Args", pascal_name);
201 let definition_name = format_ident!("{}_definition", method_name);
202
203 let description = extract_doc_comment(&method.attrs);
204 let description = if description.is_empty() {
205 format!("Tool: {}", tool_name)
206 } else {
207 description
208 };
209
210 let method_args: Vec<_> = sig
211 .inputs
212 .iter()
213 .filter_map(|arg| match arg {
214 FnArg::Typed(pat_type) => Some(pat_type),
215 FnArg::Receiver(_) => None,
216 })
217 .collect();
218 let json_args: Vec<_> = method_args
219 .iter()
220 .copied()
221 .filter(|pat_type| !is_tool_execution_context_type(pat_type.ty.as_ref()))
222 .collect();
223
224 let arg_fields: Vec<_> = json_args
225 .iter()
226 .map(|pat_type| {
227 let field_name = argument_ident(pat_type.pat.as_ref())?;
228 let ty = &pat_type.ty;
229 let description = extract_description_attr(&pat_type.attrs)?;
230
231 Ok(if let Some(description) = description {
232 quote! {
233 #[schemars(description = #description)]
234 pub #field_name: #ty
235 }
236 } else {
237 quote! {
238 pub #field_name: #ty
239 }
240 })
241 })
242 .collect::<syn::Result<_>>()?;
243
244 let call_args: Vec<_> = method_args
245 .iter()
246 .map(|pat_type| {
247 if is_tool_execution_context_type(pat_type.ty.as_ref()) {
248 Ok(quote! { ctx.clone() })
249 } else {
250 let ident = argument_ident(pat_type.pat.as_ref())?;
251 Ok(quote! { args.#ident })
252 }
253 })
254 .collect::<syn::Result<_>>()?;
255 let method_call = if call_args.is_empty() {
256 quote! { self.ctx.#method_name() }
257 } else {
258 quote! { self.ctx.#method_name(#(#call_args),*) }
259 };
260
261 let awaiter = if sig.asyncness.is_some() {
262 quote! { .await }
263 } else {
264 quote! {}
265 };
266
267 let result_handling = if is_result_type(&sig.output) {
268 quote! {
269 match result {
270 Ok(val) => Ok(format!("{:?}", val).into()),
271 Err(error) => Err(::agen::tool::ToolError::ExecutionFailed(format!("{}", error))),
272 }
273 }
274 } else {
275 quote! {
276 Ok(format!("{:?}", result).into())
277 }
278 };
279
280 let args_struct_def = quote! {
281 #[derive(
282 ::agen::__private::serde::Deserialize,
283 ::agen::__private::schemars::JsonSchema,
284 )]
285 #[serde(crate = "::agen::__private::serde")]
286 #[schemars(crate = "::agen::__private::schemars")]
287 struct #args_struct_name {
288 #(#arg_fields),*
289 }
290 };
291
292 let execute_body = if json_args.is_empty() {
293 quote! {
294 let _: #args_struct_name = ::agen::__private::serde_json::from_str(input_json)
295 .unwrap_or(#args_struct_name {});
296
297 let result = #method_call #awaiter;
298 #result_handling
299 }
300 } else {
301 quote! {
302 let args: #args_struct_name = ::agen::__private::serde_json::from_str(input_json)
303 .map_err(|error| ::agen::tool::ToolError::InvalidArgument(error.to_string()))?;
304
305 let result = #method_call #awaiter;
306 #result_handling
307 }
308 };
309
310 Ok(quote! {
311 #args_struct_def
312
313 #[derive(Clone)]
314 pub struct #tool_struct_name {
315 ctx: #self_ty,
316 }
317
318 #[::agen::__private::async_trait::async_trait]
319 impl ::agen::tool::Tool for #tool_struct_name {
320 async fn execute(
321 &self,
322 input_json: &str,
323 ctx: ::agen::tool::ToolExecutionContext,
324 ) -> Result<::agen::tool::ToolOutput, ::agen::tool::ToolError> {
325 let _ = &ctx;
326 #execute_body
327 }
328 }
329
330 impl #self_ty {
331 pub fn #definition_name(&self) -> ::agen::tool::ToolDefinition {
333 let ctx = self.clone();
334 ::std::sync::Arc::new(move || {
335 let schema = ::agen::__private::schemars::schema_for!(#args_struct_name);
336 let meta = ::agen::tool::ToolMeta::new(#tool_name)
337 .description(#description)
338 .input_schema(
339 ::agen::__private::serde_json::to_value(schema)
340 .unwrap_or_else(|_| ::agen::__private::serde_json::json!({})),
341 );
342 let tool: ::std::sync::Arc<dyn ::agen::tool::Tool> =
343 ::std::sync::Arc::new(#tool_struct_name { ctx: ctx.clone() });
344 (meta, tool)
345 })
346 }
347 }
348 })
349}
350
351fn is_result_type(return_type: &ReturnType) -> bool {
352 match return_type {
353 ReturnType::Default => false,
354 ReturnType::Type(_, ty) => {
355 if let Type::Path(type_path) = ty.as_ref()
356 && let Some(segment) = type_path.path.segments.last()
357 {
358 return segment.ident == "Result";
359 }
360 false
361 }
362 }
363}
364
365fn to_pascal_case(s: &str) -> String {
366 s.split('_')
367 .map(|part| {
368 let mut chars = part.chars();
369 match chars.next() {
370 None => String::new(),
371 Some(first) => first.to_uppercase().chain(chars).collect(),
372 }
373 })
374 .collect()
375}
376
377#[proc_macro_attribute]
379pub fn tool(attr: TokenStream, item: TokenStream) -> TokenStream {
380 marker_attribute("tool", attr, item)
381}
382
383#[proc_macro_attribute]
387pub fn description(attr: TokenStream, item: TokenStream) -> TokenStream {
388 marker_attribute("description", attr, item)
389}
390
391fn marker_attribute(name: &str, attr: TokenStream, item: TokenStream) -> TokenStream {
392 if attr.is_empty() {
393 item
394 } else {
395 syn::Error::new(
396 proc_macro2::Span::call_site(),
397 format!("{name} is a marker interpreted by #[tool_registry]"),
398 )
399 .into_compile_error()
400 .into()
401 }
402}
403
404#[cfg(test)]
405mod tests {
406 use super::*;
407 use quote::quote;
408 use syn::parse_quote;
409
410 #[test]
411 fn rejects_tool_registry_arguments() {
412 let implementation: ItemImpl = parse_quote!(impl Registry {});
413 let error = expand_tool_registry(quote!(unexpected), implementation).unwrap_err();
414
415 assert!(error.to_string().contains("does not accept arguments"));
416 }
417
418 #[test]
419 fn rejects_duplicate_tool_markers() {
420 let implementation: ItemImpl = parse_quote! {
421 impl Registry {
422 #[tool]
423 #[tool]
424 fn inspect(&self) {}
425 }
426 };
427 let error = expand_tool_registry(quote!(), implementation).unwrap_err();
428
429 assert!(error.to_string().contains("duplicate #[tool]"));
430 }
431
432 #[test]
433 fn rejects_invalid_description_attributes() {
434 let implementation: ItemImpl = parse_quote! {
435 impl Registry {
436 #[tool]
437 fn inspect(&self, #[description] input: String) {}
438 }
439 };
440 let error = expand_tool_registry(quote!(), implementation).unwrap_err();
441
442 assert!(error.to_string().contains("expected #[description"));
443 }
444
445 #[test]
446 fn rejects_duplicate_description_attributes() {
447 let implementation: ItemImpl = parse_quote! {
448 impl Registry {
449 #[tool]
450 fn inspect(
451 &self,
452 #[description = "first"]
453 #[description = "second"]
454 input: String,
455 ) {}
456 }
457 };
458 let error = expand_tool_registry(quote!(), implementation).unwrap_err();
459
460 assert!(error.to_string().contains("duplicate #[description]"));
461 }
462
463 #[test]
464 fn generated_code_uses_only_agen_runtime_paths() {
465 let implementation: ItemImpl = parse_quote! {
466 impl Registry {
467 #[tool]
468 fn inspect(&self, input: String) -> Result<String, Error> {
469 unreachable!()
470 }
471 }
472 };
473 let expanded = expand_tool_registry(quote!(), implementation)
474 .unwrap()
475 .to_string();
476
477 assert!(expanded.contains(":: agen :: tool :: Tool"));
478 assert!(expanded.contains(":: agen :: __private :: serde_json"));
479 assert!(expanded.contains(":: agen :: __private :: serde"));
480 assert!(expanded.contains(":: agen :: __private :: schemars"));
481 }
482}