Skip to main content

fauna_api/extensions/web/
tools.rs

1use std::sync::Arc;
2
3use futures_util::future::BoxFuture;
4use serde::{Deserialize, Serialize};
5use serde_json::{Map, Value, json};
6
7use crate::error::Result;
8use crate::marmot::web::WebRoom;
9use crate::parrot::generative::{Tool, tool};
10
11#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
12#[serde(rename_all = "snake_case")]
13pub enum PageToolName {
14    ReadPageHtml,
15    ReadPageText,
16    ReadSelection,
17}
18
19/// Runs one page tool with its parameters and returns its result as text.
20pub type PageToolHandler = Arc<
21    dyn Fn(PageToolName, Map<String, Value>) -> BoxFuture<'static, Result<String>> + Send + Sync,
22>;
23
24/// What a page tool resolves with: `{ text }`.
25fn page_text(text: &str) -> Value {
26    json!({
27        "type": "OBJECT",
28        "properties": { "text": { "type": "STRING", "description": text } },
29        "required": ["text"],
30    })
31}
32
33/// A page tool's text as its result.
34fn read(run: BoxFuture<'static, Result<String>>) -> BoxFuture<'static, Result<Map<String, Value>>> {
35    Box::pin(async move {
36        Ok(Map::from_iter([(
37            "text".to_string(),
38            Value::String(run.await?),
39        )]))
40    })
41}
42
43/// Parrot tools wired through a web-room invoke (or a local host handler).
44pub fn page_tools(invoke: PageToolHandler) -> Vec<Tool> {
45    let html = invoke.clone();
46    let text = invoke.clone();
47    vec![
48        tool(
49            "read_page_html",
50            "Read the cleaned HTML of the currently shared page.",
51            json!({ "type": "OBJECT", "properties": {} }),
52            page_text("The page's HTML, cut off past 200,000 characters"),
53            move |_, _| read(html(PageToolName::ReadPageHtml, Map::new())),
54        ),
55        tool(
56            "read_page_text",
57            "Read the visible text of the currently shared page.",
58            json!({ "type": "OBJECT", "properties": {} }),
59            page_text("The page's visible text, cut off past 80,000 characters"),
60            move |_, _| read(text(PageToolName::ReadPageText, Map::new())),
61        ),
62        tool(
63            "read_selection",
64            "Read the host's current text selection on the shared page.",
65            json!({
66                "type": "OBJECT",
67                "properties": {
68                    "max": { "type": "INTEGER", "description": "Max characters to return." },
69                },
70            }),
71            page_text("The selected text, or (no selection)"),
72            move |params: Value, _| {
73                read(invoke(
74                    PageToolName::ReadSelection,
75                    params.as_object().cloned().unwrap_or_default(),
76                ))
77            },
78        ),
79    ]
80}
81
82/// Bind host tool fulfillment on a connected WebRoom. Returns a function that unbinds it.
83pub fn attach_host_tools(
84    room: &WebRoom,
85    handler: PageToolHandler,
86) -> Box<dyn FnOnce() + Send + Sync> {
87    room.set_tool_handler(Arc::new(move |name: String, params: Map<String, Value>| {
88        match serde_json::from_value::<PageToolName>(Value::from(name.as_str())) {
89            Ok(tool) => handler(tool, params),
90            Err(_) => Box::pin(async move { Ok(format!("Unknown page tool: {name}")) }),
91        }
92    }))
93}
94
95#[cfg(test)]
96mod tests {
97    use std::sync::Mutex;
98
99    use serde_json::{Map, json};
100    use tokio::sync::mpsc;
101
102    use super::*;
103    use crate::authentification::{ApiKey, CredentialsOrApiKey};
104    use crate::shared::server::{Authorization, Room};
105
106    #[tokio::test]
107    async fn page_tools_reach_the_host_handler() {
108        let seen = Arc::new(Mutex::new(Vec::new()));
109        let sink = seen.clone();
110        let handler: PageToolHandler = Arc::new(move |name, params| {
111            sink.lock().unwrap().push((name, params));
112            Box::pin(async { Ok("page".to_string()) })
113        });
114        let tools = page_tools(handler.clone());
115        assert_eq!(
116            Value::Object(
117                (tools[2].evaluate)(json!({ "max": 5 }), Arc::new(|_| {}))
118                    .await
119                    .unwrap()
120            ),
121            json!({ "text": "page" })
122        );
123        assert_eq!(seen.lock().unwrap()[0].0, PageToolName::ReadSelection);
124        assert_eq!(seen.lock().unwrap()[0].1["max"], 5);
125
126        let (ws, _outbox) = mpsc::unbounded_channel();
127        let room = Room::new(
128            "http://localhost/extensions/web/live".to_string(),
129            ws,
130            Authorization::AccessCode {
131                authorization: CredentialsOrApiKey::ApiKey(ApiKey::default()),
132                access_code: "code".to_string(),
133            },
134            "web".to_string(),
135        );
136        let web = WebRoom::from_parent(&room, None, &json!({}));
137        let detach = attach_host_tools(&web, handler);
138        assert_eq!(
139            web.invoke_tool("read_page_text", Map::new(), None)
140                .await
141                .unwrap(),
142            "page"
143        );
144        assert_eq!(
145            web.invoke_tool("open_tab", Map::new(), None).await.unwrap(),
146            "Unknown page tool: open_tab"
147        );
148        detach();
149        assert_eq!(seen.lock().unwrap()[1].0, PageToolName::ReadPageText);
150    }
151}