1#![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used))]
2use proc_macro::TokenStream;
26use proc_macro2::TokenStream as TokenStream2;
27use quote::{format_ident, quote, quote_spanned};
28use syn::spanned::Spanned;
29use syn::{
30 Attribute, Expr, ExprLit, FnArg, GenericParam, Ident, ItemFn, Lit, LitStr, Pat, PatType,
31 ReturnType, Type, parse_macro_input,
32};
33
34#[proc_macro_attribute]
123pub fn tool(attr: TokenStream, item: TokenStream) -> TokenStream {
124 let args = parse_macro_input!(attr as ToolArgs);
125 let func = parse_macro_input!(item as ItemFn);
126 match expand(args, func) {
127 Ok(tokens) => tokens.into(),
128 Err(err) => err.to_compile_error().into(),
129 }
130}
131
132#[derive(Default)]
134struct ToolArgs {
135 name: Option<String>,
136 description: Option<String>,
137 approval: Option<Approval>,
138 narrate: Option<Box<Expr>>,
139}
140
141enum Approval {
143 Always,
144 When(Box<Expr>),
145}
146
147impl syn::parse::Parse for ToolArgs {
148 fn parse(input: syn::parse::ParseStream) -> syn::Result<Self> {
149 let mut args = ToolArgs::default();
150 let metas =
151 syn::punctuated::Punctuated::<syn::Meta, syn::Token![,]>::parse_terminated(input)?;
152 for meta in metas {
153 let path = meta.path().clone();
154 let key = path.get_ident().map(Ident::to_string).unwrap_or_default();
155 match (key.as_str(), meta) {
156 ("needs_approval", syn::Meta::Path(_)) => args.approval = Some(Approval::Always),
157 ("needs_approval", syn::Meta::NameValue(nv)) => {
158 args.approval = Some(Approval::When(Box::new(nv.value)));
159 }
160 ("narrate", syn::Meta::NameValue(nv)) => {
161 args.narrate = Some(Box::new(nv.value));
162 }
163 ("narrate", other) => {
164 return Err(syn::Error::new(
165 other.span(),
166 "expected `narrate = <narrator>`",
167 ));
168 }
169 ("name" | "description", syn::Meta::NameValue(nv)) => {
170 let value = lit_str(&nv.value).ok_or_else(|| {
171 syn::Error::new(nv.value.span(), "expected a string literal")
172 })?;
173 if key == "name" {
174 args.name = Some(value);
175 } else {
176 args.description = Some(value);
177 }
178 }
179 ("name" | "description", other) => {
180 return Err(syn::Error::new(
181 other.span(),
182 format!("expected `{key} = \"…\"`"),
183 ));
184 }
185 ("needs_approval", other) => {
186 return Err(syn::Error::new(
187 other.span(),
188 "expected `needs_approval` or `needs_approval = <rule>`",
189 ));
190 }
191 (other, _) => {
192 return Err(syn::Error::new(
193 path.span(),
194 format!(
195 "unknown `everruns::tool` option `{other}`; expected `name`, `description`, `needs_approval`, or `narrate`"
196 ),
197 ));
198 }
199 }
200 }
201 Ok(args)
202 }
203}
204
205fn lit_str(expr: &Expr) -> Option<String> {
207 match expr {
208 Expr::Lit(ExprLit {
209 lit: Lit::Str(s), ..
210 }) => Some(s.value()),
211 _ => None,
212 }
213}
214
215struct Field {
217 ident: Ident,
218 ty: Type,
219 rename: Option<LitStr>,
220}
221
222fn expand(args: ToolArgs, func: ItemFn) -> syn::Result<TokenStream2> {
223 let sig = &func.sig;
224
225 if sig.asyncness.is_none() {
226 return Err(syn::Error::new_spanned(
227 func.sig.fn_token,
228 "`#[everruns::tool]` requires an `async fn`",
229 ));
230 }
231
232 if let Some(param) = sig.generics.params.first() {
233 let span = match param {
234 GenericParam::Type(p) => p.span(),
235 GenericParam::Lifetime(p) => p.span(),
236 GenericParam::Const(p) => p.span(),
237 };
238 return Err(syn::Error::new(
239 span,
240 "`#[everruns::tool]` does not support generic parameters",
241 ));
242 }
243 if let Some(where_clause) = &sig.generics.where_clause {
244 return Err(syn::Error::new_spanned(
245 where_clause,
246 "`#[everruns::tool]` does not support `where` clauses",
247 ));
248 }
249
250 let mut fields: Vec<Field> = Vec::new();
254 let mut context: Option<ContextParam> = None;
255 for (index, input) in sig.inputs.iter().enumerate() {
256 match input {
257 FnArg::Receiver(receiver) => {
258 return Err(syn::Error::new_spanned(
259 receiver,
260 "`#[everruns::tool]` does not support a `self` receiver",
261 ));
262 }
263 FnArg::Typed(pat_type) => match context_param(&pat_type.ty) {
264 Some(kind) if index == 0 => context = Some(kind),
265 Some(_) => {
266 return Err(syn::Error::new_spanned(
267 &pat_type.ty,
268 "`ToolCallContext` must be the first parameter of an `#[everruns::tool]` function",
269 ));
270 }
271 None => fields.push(lower_param(pat_type)?),
272 },
273 }
274 }
275
276 let description = match args.description {
278 Some(text) => text,
279 None => doc_comment(&func.attrs),
280 };
281 if description.trim().is_empty() {
282 return Err(syn::Error::new_spanned(
283 &func.sig.ident,
284 "`#[everruns::tool]` requires a description: add a doc comment or \
285 `#[everruns::tool(description = \"…\")]`",
286 ));
287 }
288 let description = description.trim().to_string();
289
290 let fn_ident = &sig.ident;
291 let vis = &func.vis;
292 let tool_name = args.name.unwrap_or_else(|| fn_ident.to_string());
293
294 let impl_ident = format_ident!("__everruns_tool_impl_{}", fn_ident);
298 let inner_inputs = sig.inputs.iter().map(|input| match input {
299 FnArg::Typed(pat_type) => {
300 let mut cleaned = pat_type.clone();
301 cleaned.attrs.retain(|attr| !attr.path().is_ident("tool"));
302 FnArg::Typed(cleaned)
303 }
304 other => other.clone(),
305 });
306 let inner_inputs = quote! { #(#inner_inputs),* };
307 let orig_output = &sig.output;
308 let orig_body = &func.block;
309
310 let args_ident = format_ident!("{}Args", pascal_case(&fn_ident.to_string()));
315 let field_decls = fields.iter().map(|f| {
316 let ident = &f.ident;
317 let ty = &f.ty;
318 let rename = f
319 .rename
320 .as_ref()
321 .map(|name| quote!(#[serde(rename = #name)]));
322 quote! { #rename pub #ident: #ty }
323 });
324 let field_idents: Vec<&Ident> = fields.iter().map(|f| &f.ident).collect();
325
326 let dispatch = result_dispatch(orig_output, &tool_name);
327
328 let (constructor, handler_params, context_arg) = match context {
329 None => (
330 quote!(::everruns::FunctionTool::new),
331 quote!(__args: ::everruns::__macro_support::Value),
332 quote!(),
333 ),
334 Some(kind) => {
335 let pass = match kind {
336 ContextParam::Value => quote!(__ctx,),
337 ContextParam::Ref => quote!(&__ctx,),
338 };
339 (
340 quote!(::everruns::FunctionTool::with_context),
341 quote!(
342 __ctx: ::everruns::ToolCallContext,
343 __args: ::everruns::__macro_support::Value
344 ),
345 pass,
346 )
347 }
348 };
349
350 let approval = match args.approval {
351 None => quote!(),
352 Some(Approval::Always) => quote!(.always_needs_approval()),
353 Some(Approval::When(rule)) => quote! {
354 .needs_approval({
355 fn __everruns_approval_rule<
357 __F: ::core::ops::Fn(&#args_ident) -> bool
358 + ::core::marker::Send
359 + ::core::marker::Sync
360 + 'static,
361 >(rule: __F) -> __F {
362 rule
363 }
364 let __rule = __everruns_approval_rule(#rule);
365 move |__args: &::everruns::__macro_support::Value| {
366 match ::everruns::__macro_support::from_value::<#args_ident>(
367 ::core::clone::Clone::clone(__args),
368 ) {
369 ::core::result::Result::Ok(__parsed) => __rule(&__parsed),
370 ::core::result::Result::Err(_) => true,
373 }
374 }
375 })
376 },
377 };
378
379 let narrate = match args.narrate {
380 None => quote!(),
381 Some(narrator) => quote! {
382 .narrate({
383 fn __everruns_narrator<
385 __F: ::core::ops::Fn(
386 &#args_ident,
387 &::everruns::ToolNarration<'_>,
388 ) -> ::core::option::Option<::std::string::String>
389 + ::core::marker::Send
390 + ::core::marker::Sync
391 + 'static,
392 >(narrator: __F) -> __F {
393 narrator
394 }
395 let __narrator = __everruns_narrator(#narrator);
396 move |__call: &::everruns::ToolNarration<'_>| {
397 let __parsed = ::everruns::__macro_support::from_value::<#args_ident>(
400 ::core::clone::Clone::clone(__call.arguments()),
401 )
402 .ok()?;
403 __narrator(&__parsed, __call)
404 }
405 })
406 },
407 };
408
409 let expanded = quote! {
410 #[derive(
411 ::everruns::__macro_support::serde::Deserialize,
412 ::everruns::__macro_support::schemars::JsonSchema,
413 )]
414 #[serde(crate = "::everruns::__macro_support::serde")]
415 #[schemars(crate = "::everruns::__macro_support::schemars", rename = "__Args")]
416 #[allow(missing_docs, non_camel_case_types, dead_code)]
417 #vis struct #args_ident {
418 #(#field_decls,)*
419 }
420
421 #[allow(clippy::let_unit_value)]
424 #vis fn #fn_ident() -> ::everruns::FunctionTool {
425 #[allow(clippy::used_underscore_items)]
426 async fn #impl_ident(#inner_inputs) #orig_output #orig_body
427
428 let __schema = ::everruns::__macro_support::schema_for::<#args_ident>();
429
430 #constructor(
431 #tool_name,
432 #description,
433 __schema,
434 move |#handler_params| async move {
435 let __parsed: #args_ident = match ::everruns::__macro_support::from_value(__args) {
436 ::core::result::Result::Ok(__v) => __v,
437 ::core::result::Result::Err(__e) => {
438 return ::core::result::Result::Ok(
443 ::everruns::ToolResponse::error(::std::format!(
444 "invalid arguments for tool `{}`: {}",
445 #tool_name,
446 __e,
447 )),
448 );
449 }
450 };
451 let __out = #impl_ident(#context_arg #(__parsed.#field_idents),*).await;
452 #dispatch
453 },
454 )
455 #approval
456 #narrate
457 }
458 };
459
460 Ok(expanded)
461}
462
463#[derive(Clone, Copy)]
465enum ContextParam {
466 Value,
467 Ref,
468}
469
470fn context_param(ty: &Type) -> Option<ContextParam> {
473 let (ty, kind) = match ty {
474 Type::Reference(reference) if reference.mutability.is_none() => {
475 (reference.elem.as_ref(), ContextParam::Ref)
476 }
477 other => (other, ContextParam::Value),
478 };
479 let Type::Path(type_path) = ty else {
480 return None;
481 };
482 type_path
483 .path
484 .segments
485 .last()
486 .is_some_and(|segment| segment.ident == "ToolCallContext" && segment.arguments.is_empty())
487 .then_some(kind)
488}
489
490fn pascal_case(name: &str) -> String {
492 name.trim_start_matches("r#")
493 .split('_')
494 .filter(|part| !part.is_empty())
495 .map(|part| {
496 let mut chars = part.chars();
497 match chars.next() {
498 Some(first) => first.to_uppercase().chain(chars).collect::<String>(),
499 None => String::new(),
500 }
501 })
502 .collect()
503}
504
505fn lower_param(pat_type: &PatType) -> syn::Result<Field> {
508 let ident = match pat_type.pat.as_ref() {
509 Pat::Ident(pat_ident) => pat_ident.ident.clone(),
510 other => {
511 return Err(syn::Error::new_spanned(
512 other,
513 "`#[everruns::tool]` parameters must be plain identifiers (`name: Type`)",
514 ));
515 }
516 };
517 let rename = parse_rename(&pat_type.attrs)?;
518 Ok(Field {
519 ident,
520 ty: (*pat_type.ty).clone(),
521 rename,
522 })
523}
524
525fn parse_rename(attrs: &[Attribute]) -> syn::Result<Option<LitStr>> {
527 let mut rename = None;
528 for attr in attrs {
529 if !attr.path().is_ident("tool") {
530 continue;
531 }
532 attr.parse_nested_meta(|meta| {
533 if meta.path.is_ident("rename") {
534 let value = meta.value()?;
535 rename = Some(value.parse::<LitStr>()?);
536 Ok(())
537 } else {
538 Err(meta.error("expected `rename = \"…\"`"))
539 }
540 })?;
541 }
542 Ok(rename)
543}
544
545fn doc_comment(attrs: &[Attribute]) -> String {
547 let mut lines: Vec<String> = Vec::new();
548 for attr in attrs {
549 if !attr.path().is_ident("doc") {
550 continue;
551 }
552 if let syn::Meta::NameValue(nv) = &attr.meta
553 && let Some(text) = lit_str(&nv.value)
554 {
555 lines.push(text.trim().to_string());
556 }
557 }
558 lines.join("\n").trim().to_string()
559}
560
561fn result_dispatch(output: &ReturnType, tool_name: &str) -> TokenStream2 {
567 let serialize = |value: TokenStream2| {
568 quote! {
569 ::everruns::__macro_support::to_value(&#value)
570 .map(::everruns::ToolResponse::json)
571 .map_err(|__e| ::std::format!(
572 "failed to serialize result of tool `{}`: {}", #tool_name, __e,
573 ))
574 }
575 };
576 if returns_result(output) {
577 let serialize_ok = serialize(quote!(__ok));
578 quote! {
579 match __out {
580 ::core::result::Result::Ok(__ok) => { #serialize_ok }
581 ::core::result::Result::Err(__err) => ::core::result::Result::Ok(
582 ::everruns::ToolResponse::error(::std::string::ToString::to_string(&__err)),
583 ),
584 }
585 }
586 } else {
587 let serialize_out = serialize(quote!(__out));
588 quote_spanned! {output.span()=> #serialize_out }
589 }
590}
591
592fn returns_result(output: &ReturnType) -> bool {
594 let ReturnType::Type(_, ty) = output else {
595 return false;
596 };
597 let Type::Path(type_path) = ty.as_ref() else {
598 return false;
599 };
600 type_path
601 .path
602 .segments
603 .last()
604 .is_some_and(|segment| segment.ident == "Result")
605}