Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

16.1 KB
Raw Blame
//! Finishing a user tool inside the turn: the user reviews the call the model
//! made, then the host executes or rejects it.
//!
//! A user tool (`ai_toolset::UserTool`, registered with `add_user_tool`)
//! answers `"PendingUserExecution"` and does nothing. The host finishes it
//! with the pieces `ai_toolset` exposes for exactly that: `is_valid_tool` to
//! check edited arguments and `try_user_tool_call` to run the wrapped tool.
//! Chat does so after the turn, over HTTP, from its composer. A host that can
//! reach its user *during* the turn - Macro's in-process agent, whose ACP
//! client renders elicitations - does it here, through the
//! [`UserToolReviewer`] port, before the model reads the result.
//!
//! The port speaks in the restricted form vocabulary elicitation shares
//! across ACP and MCP (flat primitives with defaults), stated in this crate's
//! own types so neither protocol leaks in. A [`ReviewForm`] is projected from
//! the tool's input schema and the call's arguments, so every user tool is
//! reviewable without per-tool code; the whole edited draft can come back in
//! one `Json` field for a client that has a composer of its own.

use std::collections::BTreeMap;
use std::future::Future;
use std::pin::Pin;
use std::sync::Arc;

use agent::{FinishedUserTool, PendingUserTool, UserToolFinisher};
use ai_toolset::tool_object::UserToolResponse;
use ai_toolset::{AsyncToolCollection, RequestContext};
use async_trait::async_trait;
use macro_user_id::user_id::MacroUserIdStr;
use serde_json::{Map, Value};
use tokio_util::sync::CancellationToken;

#[cfg(test)]
mod test;

/// The name of the form field that carries the whole edited draft as JSON.
/// A client with its own composer for the tool fills this in; a client that
/// renders the form generically leaves it out and edits the flat fields.
pub const DRAFT_FIELD: &str = "draft";

/// A user tool's call, put to the user for review.
#[derive(Debug, Clone, PartialEq)]
pub struct ReviewRequest {
    /// The tool's name as the toolset knows it.
    pub tool_name: String,
    /// The call's id as the transcript shows it.
    pub tool_call_id: String,
    /// What the user is asked, in one line: "Create calendar event?".
    pub message: String,
    /// The arguments the model called the tool with, whole.
    pub draft: Value,
    /// The flat form a client renders to edit the draft.
    pub form: ReviewForm,
}

/// A flat form: the restricted schema elicitation allows, in neutral terms.
#[derive(Debug, Clone, PartialEq, Default)]
pub struct ReviewForm {
    /// The tool's human title, for the form's heading.
    pub title: Option<String>,
    /// The fields, in the schema's order.
    pub fields: Vec<ReviewField>,
    /// Names of the fields an answer must fill.
    pub required: Vec<String>,
}

/// One form field.
#[derive(Debug, Clone, PartialEq)]
pub struct ReviewField {
    /// The key the answer is sent back under; the argument it edits.
    pub name: String,
    /// The argument's description from the tool's schema, when it has one.
    pub description: Option<String>,
    /// The field's type and pre-filled value.
    pub kind: ReviewFieldKind,
}

/// A field's type, with the value the draft holds as its default.
#[derive(Debug, Clone, PartialEq)]
pub enum ReviewFieldKind {
    /// Free text; `format` is the schema's (`date-time`, `email`, ...) when given.
    Text {
        /// The draft's value.
        default: Option<String>,
        /// The schema's format hint.
        format: Option<String>,
    },
    /// A yes/no.
    Boolean {
        /// The draft's value.
        default: Option<bool>,
    },
    /// A number.
    Number {
        /// The draft's value.
        default: Option<f64>,
    },
    /// A whole number.
    Integer {
        /// The draft's value.
        default: Option<i64>,
    },
    /// One of a fixed set of strings.
    Choice {
        /// The allowed values.
        options: Vec<String>,
        /// The draft's value.
        default: Option<String>,
    },
    /// The whole edited draft as a JSON string - see [`DRAFT_FIELD`].
    Json,
}

/// What the user decided.
#[derive(Debug, Clone, PartialEq)]
pub enum ReviewOutcome {
    /// The user confirmed, with the form's values as submitted. Absent
    /// fields keep the draft's values.
    Accepted(BTreeMap<String, Value>),
    /// The user said no.
    Declined,
    /// The question was dismissed, or the turn stopped.
    Cancelled,
}

/// Why a review could not happen.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum ReviewError {
    /// The user cannot be asked right now: the client has no way to show the
    /// form, or is already holding another question.
    #[error("the user cannot be asked to review this call right now: {0}")]
    Unavailable(String),
    /// Asking failed on the way.
    #[error("asking the user to review this call failed: {0}")]
    Failed(String),
}

/// A host's way of putting a call to its user and waiting for the answer.
#[async_trait]
pub trait UserToolReviewer: Send + Sync {
    /// Ask the user to review `request` and wait for their decision.
    async fn review(&self, request: ReviewRequest) -> Result<ReviewOutcome, ReviewError>;
}

/// A [`UserToolFinisher`] for `tools`: puts each pending user tool to
/// `reviewer`, and on acceptance runs the tool with the reviewed arguments
/// as `user`, against `context`.
///
/// The tool's answer is a `UserToolResponse` as JSON, the same shape chat
/// writes when its composer finishes the call: the user's action with the
/// tool's result, or `"Rejected"`. A tool this toolset does not know as a
/// user tool is left alone (`None`) for the host to finish some other way.
pub fn user_tool_finisher<Context>(
    tools: Arc<AsyncToolCollection<Context>>,
    context: Context,
    user: MacroUserIdStr<'static>,
    reviewer: Arc<dyn UserToolReviewer>,
    cancel: CancellationToken,
) -> UserToolFinisher
where
    Context: Clone + Send + Sync + 'static,
{
    let authorize: UserToolAuthorizer = Arc::new(move |_, _| {
        let user = user.clone();
        Box::pin(async move { Ok(user) })
    });
    authorized_user_tool_finisher(tools, context, reviewer, cancel, authorize)
}

/// Resolve and authorize the actual reviewed arguments immediately before execution.
pub type UserToolAuthorizer = Arc<
    dyn Fn(
            String,
            Value,
        )
            -> Pin<Box<dyn Future<Output = Result<MacroUserIdStr<'static>, ReviewError>> + Send>>
        + Send
        + Sync,
>;

/// Review a draft first, then authorize its final arguments and selected account.
/// The approval therefore covers the edited action, not the model's earlier draft.
pub fn authorized_user_tool_finisher<Context>(
    tools: Arc<AsyncToolCollection<Context>>,
    context: Context,
    reviewer: Arc<dyn UserToolReviewer>,
    cancel: CancellationToken,
    authorize: UserToolAuthorizer,
) -> UserToolFinisher
where
    Context: Clone + Send + Sync + 'static,
{
    Arc::new(move |call: PendingUserTool| {
        let tools = Arc::clone(&tools);
        let context = context.clone();
        let authorize = Arc::clone(&authorize);
        let reviewer = Arc::clone(&reviewer);
        let cancel = cancel.clone();
        Box::pin(async move { finish(&tools, context, &authorize, &*reviewer, cancel, call).await })
            as Pin<Box<dyn Future<Output = Option<FinishedUserTool>> + Send>>
    })
}

async fn finish<Context>(
    tools: &AsyncToolCollection<Context>,
    context: Context,
    authorize: &UserToolAuthorizer,
    reviewer: &dyn UserToolReviewer,
    cancel: CancellationToken,
    call: PendingUserTool,
) -> Option<FinishedUserTool>
where
    Context: Clone + Send + Sync + 'static,
{
    let tool = tools.user_tools.get(&call.tool_name)?;
    let request = ReviewRequest {
        tool_name: call.tool_name.clone(),
        tool_call_id: call.tool_call_id.clone(),
        message: format!("{}?", tool.annotations.title),
        draft: call.args.clone(),
        form: project_form(
            Some(tool.annotations.title.to_owned()),
            &tool.input_schema,
            &call.args,
        ),
    };

    let outcome = match reviewer.review(request).await {
        Ok(outcome) => outcome,
        Err(error) => return Some(FinishedUserTool::Error(error.to_string())),
    };
    let content = match outcome {
        ReviewOutcome::Accepted(content) => content,
        ReviewOutcome::Declined => {
            return Some(FinishedUserTool::Result(rejected()));
        }
        ReviewOutcome::Cancelled => {
            return Some(FinishedUserTool::Error(
                "the user cancelled the review; the call was not made".to_owned(),
            ));
        }
    };

    let args = apply_review(&call.args, &content);
    if !tools.is_valid_tool(&call.tool_name, &args) {
        return Some(FinishedUserTool::Error(format!(
            "the reviewed arguments are not valid for {}; nothing was done",
            call.tool_name
        )));
    }
    let user = match authorize(call.tool_name.clone(), args.clone()).await {
        Ok(user) => user,
        Err(error) => return Some(FinishedUserTool::Error(error.to_string())),
    };
    if cancel.is_cancelled() {
        return Some(FinishedUserTool::Error(
            "The turn was cancelled; nothing was done.".into(),
        ));
    }
    let mut request_context = RequestContext::new(user);
    request_context.cancel = cancel;
    match tools
        .try_user_tool_call(context, request_context, &call.tool_name, &args)
        .await
    {
        Ok(Ok(response)) => Some(match serde_json::to_value(response) {
            Ok(json) => FinishedUserTool::Result(json),
            Err(error) => {
                FinishedUserTool::Error(format!("the result could not be encoded: {error}"))
            }
        }),
        Ok(Err(error)) => Some(FinishedUserTool::Error(error.description)),
        Err(error) => Some(FinishedUserTool::Error(error.to_string())),
    }
}

/// `UserToolResponse::Rejected` as the JSON chat writes for it.
fn rejected() -> Value {
    serde_json::to_value(UserToolResponse::<Value>::Rejected).unwrap_or(Value::Null)
}

/// The arguments to run with: the draft, overwritten by what the user
/// submitted. A whole draft under [`DRAFT_FIELD`] (a JSON string, or the
/// object itself) replaces everything; otherwise each flat field replaces
/// the argument of the same name.
pub fn apply_review(draft: &Value, content: &BTreeMap<String, Value>) -> Value {
    if let Some(whole) = content.get(DRAFT_FIELD) {
        let parsed = match whole {
            Value::String(text) => serde_json::from_str::<Value>(text).ok(),
            Value::Object(_) => Some(whole.clone()),
            _ => None,
        };
        if let Some(object @ Value::Object(_)) = parsed {
            return object;
        }
    }
    let mut args = match draft {
        Value::Object(map) => map.clone(),
        _ => Map::new(),
    };
    for (name, value) in content {
        if name != DRAFT_FIELD {
            args.insert(name.clone(), value.clone());
        }
    }
    Value::Object(args)
}

/// The flat form for a tool: one field per top-level primitive argument in
/// `schema`, pre-filled from `args`, plus the [`DRAFT_FIELD`]. Arguments the
/// restricted form cannot show - objects, arrays, unions - are left to the
/// draft field.
pub fn project_form(
    title: Option<String>,
    schema: &Map<String, Value>,
    args: &Value,
) -> ReviewForm {
    let properties = schema
        .get("properties")
        .and_then(Value::as_object)
        .cloned()
        .unwrap_or_default();
    let schema_required: Vec<&str> = schema
        .get("required")
        .and_then(Value::as_array)
        .map(|names| names.iter().filter_map(Value::as_str).collect())
        .unwrap_or_default();

    let mut fields = Vec::new();
    let mut required = Vec::new();
    for (name, property) in &properties {
        let Some(kind) = field_kind(property, args.get(name)) else {
            continue;
        };
        if schema_required.contains(&name.as_str()) {
            required.push(name.clone());
        }
        fields.push(ReviewField {
            name: name.clone(),
            description: property
                .get("description")
                .and_then(Value::as_str)
                .map(str::to_owned),
            kind,
        });
    }
    fields.push(ReviewField {
        name: DRAFT_FIELD.to_owned(),
        description: Some(
            "The complete edited arguments as JSON, for a client with its own editor. \
             When present it replaces every other field."
                .to_owned(),
        ),
        kind: ReviewFieldKind::Json,
    });
    ReviewForm {
        title,
        fields,
        required,
    }
}

/// The field a property renders as, or `None` when the restricted form has
/// no shape for it.
fn field_kind(property: &Value, current: Option<&Value>) -> Option<ReviewFieldKind> {
    // `Option<T>` fields come out as `{"type": ["string", "null"]}` or
    // `anyOf: [T, null]`; read through to the one non-null type.
    let property = non_null(property);
    if let Some(options) = choice_options(property) {
        return Some(ReviewFieldKind::Choice {
            options,
            default: current.and_then(Value::as_str).map(str::to_owned),
        });
    }
    match json_type(property)? {
        "string" => Some(ReviewFieldKind::Text {
            default: current.and_then(Value::as_str).map(str::to_owned),
            format: property
                .get("format")
                .and_then(Value::as_str)
                .map(str::to_owned),
        }),
        "boolean" => Some(ReviewFieldKind::Boolean {
            default: current.and_then(Value::as_bool),
        }),
        "integer" => Some(ReviewFieldKind::Integer {
            default: current.and_then(Value::as_i64),
        }),
        "number" => Some(ReviewFieldKind::Number {
            default: current.and_then(Value::as_f64),
        }),
        _ => None,
    }
}

/// The string values a property allows, when it is a choice among fixed
/// strings: a plain `enum`, or - how a documented Rust enum comes out - an
/// `anyOf`/`oneOf` whose every real variant is one `const` string (or a
/// one-value `enum`).
fn choice_options(property: &Value) -> Option<Vec<String>> {
    if let Some(options) = property.get("enum").and_then(Value::as_array) {
        let options: Vec<String> = options
            .iter()
            .filter_map(Value::as_str)
            .map(str::to_owned)
            .collect();
        return (!options.is_empty()).then_some(options);
    }
    let variants = ["anyOf", "oneOf"]
        .into_iter()
        .find_map(|key| property.get(key).and_then(Value::as_array))?;
    let mut options = Vec::new();
    for variant in variants {
        if json_type(variant) == Some("null") {
            continue;
        }
        let value = variant.get("const").and_then(Value::as_str).or_else(|| {
            match variant.get("enum").and_then(Value::as_array)?.as_slice() {
                [only] => only.as_str(),
                _ => None,
            }
        })?;
        options.push(value.to_owned());
    }
    (!options.is_empty()).then_some(options)
}

/// The property with a nullable wrapper removed: `anyOf`/`oneOf` of one real
/// schema and `null` reads as that schema.
fn non_null(property: &Value) -> &Value {
    for key in ["anyOf", "oneOf"] {
        if let Some(variants) = property.get(key).and_then(Value::as_array) {
            let real: Vec<&Value> = variants
                .iter()
                .filter(|variant| json_type(variant) != Some("null"))
                .collect();
            if let [only] = real[..] {
                return only;
            }
        }
    }
    property
}

/// The one JSON type a property declares, reading `["string", "null"]` as
/// `string`. `None` for a property with several real types or none.
fn json_type(property: &Value) -> Option<&str> {
    match property.get("type")? {
        Value::String(name) => Some(name.as_str()),
        Value::Array(names) => {
            let real: Vec<&str> = names
                .iter()
                .filter_map(Value::as_str)
                .filter(|name| *name != "null")
                .collect();
            match real[..] {
                [only] => Some(only),
                _ => None,
            }
        }
        _ => None,
    }
}