Skip to main content

fauna_api/termite/
os.rs

1//! A live machine: one running boot of a Repository. It's a PageRoom whose
2//! page is the machine's desktop, one HTML page that is the whole OS, so it
3//! streams like any browser room. Window tools, file tools, exec, and stop ride
4//! the same socket as `machine-call`.
5
6use std::collections::{HashMap, HashSet};
7use std::ops::Deref;
8use std::sync::{Arc, Mutex, MutexGuard, PoisonError};
9use std::time::Duration;
10
11use chrono::{DateTime, Utc};
12use futures_util::future::BoxFuture;
13use serde::{Deserialize, Serialize};
14use serde_json::{Map, Value, json};
15use tokio::sync::oneshot;
16
17use super::versioning::Repository;
18use crate::authentification::CredentialsOrApiKey;
19use crate::billing::PageQuery;
20use crate::error::{Error, Result};
21use crate::groups::Group;
22use crate::marmot::browser::{
23    BrowserRoomHooks, BrowserTool, PageRoom, js_number, js_string,
24    parrot_tools as browser_parrot_tools, present, tool,
25};
26use crate::marmot::web::{BootstrapMeta, HtmlPointer};
27use crate::parrot::generative::{Function, Tool, Usage};
28use crate::shared::schema::Schema;
29use crate::shared::server::{Authorization, Hooks, Presence, Room, connect as connect_server};
30
31/// `'web' | 'files' | 'file' | 'terminal'` in the TypeScript SDK.
32#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
33#[serde(rename_all = "lowercase")]
34pub enum WindowApp {
35    Web,
36    Files,
37    File,
38    Terminal,
39}
40
41#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
42#[serde(tag = "kind", rename_all = "lowercase")]
43pub enum WindowTool {
44    Windows,
45    Focus {
46        window: f64,
47    },
48    Place {
49        window: f64,
50        x: f64,
51        y: f64,
52    },
53    Resize {
54        window: f64,
55        width: f64,
56        height: f64,
57    },
58    Close {
59        window: f64,
60    },
61    /// Load a Web window's page again, after its files change. Previews follow their file on their own.
62    Reload {
63        window: f64,
64    },
65    /// A web window at `url`; a files window at `path` (a folder of /repository); a preview of the
66    /// file at `path`, which follows the file as it changes; or a terminal, running `command` in
67    /// view and staying open at a prompt when it ends.
68    Open {
69        app: WindowApp,
70        #[serde(default, skip_serializing_if = "Option::is_none")]
71        url: Option<String>,
72        #[serde(default, skip_serializing_if = "Option::is_none")]
73        path: Option<String>,
74        #[serde(default, skip_serializing_if = "Option::is_none")]
75        command: Option<String>,
76    },
77    /// A chord like ['ctrl', 's']. Focuses `window` first when given.
78    Key {
79        keys: Vec<String>,
80        #[serde(default, skip_serializing_if = "Option::is_none")]
81        window: Option<f64>,
82    },
83}
84
85/// `'files' | 'lines' | 'count'` in the TypeScript SDK.
86#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
87#[serde(rename_all = "lowercase")]
88pub enum GrepOutput {
89    Files,
90    Lines,
91    Count,
92}
93
94/// Paths are relative to /repository, and `/` is the repository root.
95#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
96#[serde(
97    tag = "kind",
98    rename_all = "lowercase",
99    rename_all_fields = "camelCase"
100)]
101pub enum FileTool {
102    List {
103        #[serde(default, skip_serializing_if = "Option::is_none")]
104        path: Option<String>,
105        #[serde(default, skip_serializing_if = "Option::is_none")]
106        pattern: Option<String>,
107    },
108    Grep {
109        pattern: String,
110        #[serde(default, skip_serializing_if = "Option::is_none")]
111        path: Option<String>,
112        #[serde(default, skip_serializing_if = "Option::is_none")]
113        glob: Option<String>,
114        #[serde(default, skip_serializing_if = "Option::is_none")]
115        ignore_case: Option<bool>,
116        #[serde(default, skip_serializing_if = "Option::is_none")]
117        context: Option<f64>,
118        #[serde(default, skip_serializing_if = "Option::is_none")]
119        output: Option<GrepOutput>,
120        #[serde(default, skip_serializing_if = "Option::is_none")]
121        max: Option<f64>,
122    },
123    Read {
124        path: String,
125        #[serde(default, skip_serializing_if = "Option::is_none")]
126        line: Option<f64>,
127        #[serde(default, skip_serializing_if = "Option::is_none")]
128        before: Option<f64>,
129        #[serde(default, skip_serializing_if = "Option::is_none")]
130        after: Option<f64>,
131    },
132    Write {
133        path: String,
134        text: String,
135    },
136    Replace {
137        path: String,
138        old: String,
139        new: String,
140        #[serde(default, skip_serializing_if = "Option::is_none")]
141        all: Option<bool>,
142    },
143    Insert {
144        path: String,
145        after: f64,
146        text: String,
147    },
148    Remove {
149        path: String,
150        start: f64,
151        end: f64,
152    },
153}
154
155/// `'cpu' | 'memory'` in the TypeScript SDK.
156#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
157#[serde(rename_all = "lowercase")]
158pub enum ProcessSort {
159    Cpu,
160    Memory,
161}
162
163/// `'TERM' | 'KILL'` in the TypeScript SDK.
164#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
165#[serde(rename_all = "UPPERCASE")]
166pub enum ProcessSignal {
167    Term,
168    Kill,
169}
170
171/// The guest's processes. `kill` stops only the agent user's own, never the machine's or the desktop's.
172#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
173#[serde(tag = "kind", rename_all = "lowercase")]
174pub enum ProcessTool {
175    Processes {
176        #[serde(default, skip_serializing_if = "Option::is_none")]
177        sort: Option<ProcessSort>,
178        #[serde(default, skip_serializing_if = "Option::is_none")]
179        limit: Option<f64>,
180        #[serde(default, skip_serializing_if = "Option::is_none")]
181        filter: Option<String>,
182    },
183    Kill {
184        pid: f64,
185        #[serde(default, skip_serializing_if = "Option::is_none")]
186        signal: Option<ProcessSignal>,
187    },
188}
189
190/// Pointer and keyboard input on the desktop: the browser tools but
191/// `executeJavascript`, which would run on the desktop page itself, and `search`
192/// and `exit`, which belong to a web page's agent.
193pub type DesktopTool = BrowserTool;
194
195#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
196#[serde(untagged)]
197#[allow(clippy::large_enum_variant)]
198pub enum MachineTool {
199    Desktop(DesktopTool),
200    Window(WindowTool),
201    File(FileTool),
202    Process(ProcessTool),
203}
204
205/// `'app' | 'web' | 'files' | 'preview'` in the TypeScript SDK.
206#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
207#[serde(rename_all = "lowercase")]
208pub enum WindowKind {
209    App,
210    Web,
211    Files,
212    Preview,
213}
214
215/// Metadata for one desktop window. Its pixels live in the desktop HTML.
216#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
217pub struct Window {
218    /// Same id as the element's data-window and the window tools.
219    pub id: u64,
220    pub kind: WindowKind,
221    /// WM_CLASS for apps ('xterm'), 'web', 'files', or 'preview'.
222    pub app: String,
223    pub title: String,
224    pub x: f64,
225    pub y: f64,
226    pub width: f64,
227    pub height: f64,
228    pub focused: bool,
229}
230
231fn truthy(value: &Value) -> bool {
232    match value {
233        Value::Null => false,
234        Value::Bool(value) => *value,
235        Value::Number(number) => number
236            .as_f64()
237            .is_some_and(|number| number != 0.0 && !number.is_nan()),
238        Value::String(text) => !text.is_empty(),
239        _ => true,
240    }
241}
242
243impl Window {
244    pub fn from_json(json: &Value) -> Window {
245        let kind = match json["kind"].as_str() {
246            Some("web") => WindowKind::Web,
247            Some("files") => WindowKind::Files,
248            Some("preview") => WindowKind::Preview,
249            _ => WindowKind::App,
250        };
251        let kind_name = match kind {
252            WindowKind::App => "app",
253            WindowKind::Web => "web",
254            WindowKind::Files => "files",
255            WindowKind::Preview => "preview",
256        };
257        Window {
258            id: js_number(json.get("id")) as u64,
259            kind,
260            app: js_string(json.get("app"), kind_name),
261            title: js_string(json.get("title"), ""),
262            x: json["x"].as_f64().unwrap_or_default(),
263            y: json["y"].as_f64().unwrap_or_default(),
264            width: json["width"].as_f64().unwrap_or_default(),
265            height: json["height"].as_f64().unwrap_or_default(),
266            focused: truthy(&json["focused"]),
267        }
268    }
269}
270
271/// `'list' | 'cozy'` in the TypeScript SDK.
272#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
273#[serde(rename_all = "lowercase")]
274pub enum FilesView {
275    List,
276    Cozy,
277}
278
279/// The folder and view a Files window is on. The controller sets it; every seat follows.
280#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
281pub struct FilesState {
282    pub path: String,
283    pub view: FilesView,
284}
285
286impl FilesState {
287    pub fn from_json(json: &Value) -> FilesState {
288        FilesState {
289            path: js_string(json.get("path"), ""),
290            view: if json["view"] == "cozy" {
291                FilesView::Cozy
292            } else {
293                FilesView::List
294            },
295        }
296    }
297}
298
299#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
300#[serde(rename_all = "UPPERCASE")]
301pub enum MachineStatus {
302    Booting,
303    Running,
304    Stopping,
305    Stopped,
306    Failed,
307}
308
309#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
310pub struct Viewport {
311    pub width: f64,
312    pub height: f64,
313}
314
315/// `{ min, max }` in the TypeScript SDK.
316#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
317pub struct ViewportBounds {
318    pub min: Viewport,
319    pub max: Viewport,
320}
321
322/// The smallest and largest desktop a machine draws. The largest is the guest's X screen.
323pub const VIEWPORT: ViewportBounds = ViewportBounds {
324    min: Viewport {
325        width: 640.0,
326        height: 400.0,
327    },
328    max: Viewport {
329        width: 2560.0,
330        height: 1600.0,
331    },
332};
333
334/// A desktop size inside `VIEWPORT`, in whole pixels.
335pub fn clamp_viewport(size: Viewport) -> Viewport {
336    Viewport {
337        width: size
338            .width
339            .clamp(VIEWPORT.min.width, VIEWPORT.max.width)
340            .round(),
341        height: size
342            .height
343            .clamp(VIEWPORT.min.height, VIEWPORT.max.height)
344            .round(),
345    }
346}
347
348/// Machine room hooks: the page room's, plus the machine's own. Every method
349/// defaults to a no-op.
350pub trait MachineRoomHooks: BrowserRoomHooks {
351    /// A window opened, moved, resized, retitled, or changed focus.
352    fn on_window(&self, _room: &MachineRoom, _window: &Window) {}
353    fn on_window_closed(&self, _room: &MachineRoom, _id: u64) {}
354    /// A Files window's folder or view changed.
355    fn on_files(&self, _room: &MachineRoom, _window: u64, _files: &FilesState) {}
356    fn on_status(&self, _room: &MachineRoom) {}
357    /// Private turned on or off, or couldn't stay on (`private_reason` says why).
358    fn on_private(&self, _room: &MachineRoom) {}
359    /// An agent holding the machine took a step.
360    fn on_agent_step(&self, _room: &MachineRoom, _step: &AgentStep) {}
361}
362
363impl MachineRoomHooks for () {}
364
365/// One tool call of an agent working the machine: the tool, with what, and what came back. A turn
366/// with several calls arrives as several steps. Args and result are capped at about 2 KB; larger
367/// args arrive as `{ truncated }`.
368#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
369#[serde(rename_all = "camelCase")]
370pub struct AgentStep {
371    /// The agent's id, as in the room's control state.
372    pub agent: String,
373    /// The turn, counting from 1.
374    pub step: u64,
375    /// The call's place in its turn, from 0.
376    pub call: u64,
377    pub tool: String,
378    #[serde(default)]
379    pub args: Map<String, Value>,
380    #[serde(default)]
381    pub result: String,
382    /// The turn's model time and usage ride on its first call, so totals add up.
383    #[serde(default)]
384    pub model_ms: f64,
385    #[serde(default)]
386    pub tool_ms: f64,
387    #[serde(default)]
388    pub usage: Usage,
389}
390
391const DESKTOP_TOOLS: [&str; 5] = ["move", "click", "drag", "scroll", "type"];
392const CALL_MS: u64 = 60_000;
393const EXEC_MS: u64 = 120_000;
394const STOP_MS: u64 = 10 * 60_000;
395
396/// Runs one machine tool and returns its result as text.
397pub type MachineToolInvoker =
398    Arc<dyn Fn(MachineTool) -> BoxFuture<'static, Result<String>> + Send + Sync>;
399
400/// Runs a shell command, with an optional timeout in milliseconds, and returns its result as text.
401pub type ExecInvoker =
402    Arc<dyn Fn(String, Option<f64>) -> BoxFuture<'static, Result<String>> + Send + Sync>;
403
404fn optional_text(p: &Value, key: &str) -> Option<String> {
405    present(p.get(key)).map(|value| js_string(Some(value), ""))
406}
407
408fn optional_number(p: &Value, key: &str) -> Option<f64> {
409    present(p.get(key)).map(|value| js_number(Some(value)))
410}
411
412/// Every machine tool for a model: desktop input, windows, files, and exec.
413/// `invoke` runs a tool; `exec` runs a shell command and returns its result as text.
414pub fn parrot_tools(invoke: MachineToolInvoker, exec: ExecInvoker) -> Vec<Tool> {
415    let desktop = invoke.clone();
416    let mut tools = browser_parrot_tools(
417        &DESKTOP_TOOLS
418            .iter()
419            .map(|kind| kind.to_string())
420            .collect::<HashSet<_>>(),
421        Arc::new(move |tool| desktop(MachineTool::Desktop(tool))),
422    );
423    let mut add = |name: &str,
424                   description: &str,
425                   properties: Value,
426                   required: &[&str],
427                   build: fn(&Value) -> MachineTool| {
428        let mut parameters = json!({ "type": "OBJECT", "properties": properties });
429        if !required.is_empty() {
430            parameters["required"] = json!(required);
431        }
432        let invoke = invoke.clone();
433        tools.push(tool(name, description, parameters, move |params: Value| {
434            let params = if params.is_null() { json!({}) } else { params };
435            invoke(build(&params))
436        }));
437    };
438
439    add(
440        "windows",
441        "List every open desktop window with its id, kind, app, title, position, size, and focus.",
442        json!({}),
443        &[],
444        |_| MachineTool::Window(WindowTool::Windows),
445    );
446    add(
447        "focus",
448        "Bring a window to the front and give it keyboard focus.",
449        json!({
450            "window": { "type": "NUMBER", "description": "Window id" },
451        }),
452        &["window"],
453        |p| {
454            MachineTool::Window(WindowTool::Focus {
455                window: js_number(p.get("window")),
456            })
457        },
458    );
459    add(
460        "place",
461        "Move a window so its top left corner is at desktop coordinates.",
462        json!({
463            "window": { "type": "NUMBER", "description": "Window id" },
464            "x": { "type": "NUMBER", "description": "Desktop X pixel" },
465            "y": { "type": "NUMBER", "description": "Desktop Y pixel" },
466        }),
467        &["window", "x", "y"],
468        |p| {
469            MachineTool::Window(WindowTool::Place {
470                window: js_number(p.get("window")),
471                x: js_number(p.get("x")),
472                y: js_number(p.get("y")),
473            })
474        },
475    );
476    add(
477        "resize",
478        "Resize a window. Apps redraw at the new size.",
479        json!({
480            "window": { "type": "NUMBER", "description": "Window id" },
481            "width": { "type": "NUMBER", "description": "Width in pixels" },
482            "height": { "type": "NUMBER", "description": "Height in pixels" },
483        }),
484        &["window", "width", "height"],
485        |p| {
486            MachineTool::Window(WindowTool::Resize {
487                window: js_number(p.get("window")),
488                width: js_number(p.get("width")),
489                height: js_number(p.get("height")),
490            })
491        },
492    );
493    add(
494        "close",
495        "Close a window.",
496        json!({
497            "window": { "type": "NUMBER", "description": "Window id" },
498        }),
499        &["window"],
500        |p| {
501            MachineTool::Window(WindowTool::Close {
502                window: js_number(p.get("window")),
503            })
504        },
505    );
506    add(
507        "reload",
508        "Reload a Web window after its page's files change, so it shows them. Previews follow their file on their own, and reload too.",
509        json!({
510            "window": { "type": "NUMBER", "description": "Window id" },
511        }),
512        &["window"],
513        |p| {
514            MachineTool::Window(WindowTool::Reload {
515                window: js_number(p.get("window")),
516            })
517        },
518    );
519    add(
520        "open",
521        "Open a window on the desktop: web opens a Web window at url (http or https; serve local pages over HTTP first, since file:// pages don't load); files opens a Files window at a folder; file previews a file (images, PDFs, video, audio, text); terminal opens a terminal, running command in view; when it ends the window stays open at a prompt, so people can read the result and you can type more. A preview follows its file as it changes.",
522        json!({
523            "app": { "type": "STRING", "enum": ["web", "files", "file", "terminal"], "description": "web, files, file or terminal" },
524            "url": { "type": "STRING", "description": "http or https address for a web window" },
525            "path": { "type": "STRING", "description": "Folder for files, or the file to preview, relative to /repository" },
526            "command": { "type": "STRING", "description": "Command for a terminal to run in view" },
527        }),
528        &["app"],
529        |p| {
530            MachineTool::Window(WindowTool::Open {
531                app: match p.get("app").and_then(Value::as_str) {
532                    Some("files") => WindowApp::Files,
533                    Some("file") => WindowApp::File,
534                    Some("terminal") => WindowApp::Terminal,
535                    _ => WindowApp::Web,
536                },
537                url: optional_text(p, "url"),
538                path: optional_text(p, "path"),
539                command: optional_text(p, "command"),
540            })
541        },
542    );
543    add(
544        "key",
545        "Press a key chord, like ctrl and s together. Focuses the window first when given. ctrl r or f5 on a Web window reloads it.",
546        json!({
547            "keys": { "type": "ARRAY", "items": { "type": "STRING" }, "description": "Keys held together, e.g. [\"ctrl\", \"s\"]" },
548            "window": { "type": "NUMBER", "description": "Window id to focus first" },
549        }),
550        &["keys"],
551        |p| {
552            MachineTool::Window(WindowTool::Key {
553                keys: p
554                    .get("keys")
555                    .and_then(Value::as_array)
556                    .map(|keys| keys.iter().map(|key| js_string(Some(key), "")).collect())
557                    .unwrap_or_default(),
558                window: optional_number(p, "window"),
559            })
560        },
561    );
562
563    add(
564        "list",
565        "List files under a folder of /repository. Folders end in a slash. With pattern (like **/*.ts) it matches recursively.",
566        json!({
567            "path": { "type": "STRING", "description": "Folder relative to /repository. Defaults to the root." },
568            "pattern": { "type": "STRING", "description": "Glob to match recursively" },
569        }),
570        &[],
571        |p| {
572            MachineTool::File(FileTool::List {
573                path: optional_text(p, "path"),
574                pattern: optional_text(p, "pattern"),
575            })
576        },
577    );
578    add(
579        "grep",
580        "Search file contents in /repository with ripgrep. Output is matching files by default, or lines with context, or counts.",
581        json!({
582            "pattern": { "type": "STRING", "description": "Regular expression" },
583            "path": { "type": "STRING", "description": "Folder or file to search" },
584            "glob": { "type": "STRING", "description": "Only files matching this glob" },
585            "ignoreCase": { "type": "BOOLEAN", "description": "Case insensitive" },
586            "context": { "type": "NUMBER", "description": "Lines of context around each match" },
587            "output": { "type": "STRING", "enum": ["files", "lines", "count"], "description": "files, lines, or count" },
588            "max": { "type": "NUMBER", "description": "Result cap, default 50" },
589        }),
590        &["pattern"],
591        |p| {
592            MachineTool::File(FileTool::Grep {
593                pattern: js_string(p.get("pattern"), ""),
594                path: optional_text(p, "path"),
595                glob: optional_text(p, "glob"),
596                ignore_case: present(p.get("ignoreCase")).map(truthy),
597                context: optional_number(p, "context"),
598                output: present(p.get("output"))
599                    .and_then(|output| serde_json::from_value(output.clone()).ok()),
600                max: optional_number(p, "max"),
601            })
602        },
603    );
604    add(
605        "read",
606        "Read numbered lines of a file: from line minus before to line plus after. Defaults to the first 100 lines.",
607        json!({
608            "path": { "type": "STRING", "description": "File relative to /repository" },
609            "line": { "type": "NUMBER", "description": "Line to center on, default 1" },
610            "before": { "type": "NUMBER", "description": "Lines before, default 0" },
611            "after": { "type": "NUMBER", "description": "Lines after, default 100" },
612        }),
613        &["path"],
614        |p| {
615            MachineTool::File(FileTool::Read {
616                path: js_string(p.get("path"), ""),
617                line: optional_number(p, "line"),
618                before: optional_number(p, "before"),
619                after: optional_number(p, "after"),
620            })
621        },
622    );
623    add(
624        "write",
625        "Create or overwrite a file, creating missing folders.",
626        json!({
627            "path": { "type": "STRING", "description": "File relative to /repository" },
628            "text": { "type": "STRING", "description": "Full file contents" },
629        }),
630        &["path", "text"],
631        |p| {
632            MachineTool::File(FileTool::Write {
633                path: js_string(p.get("path"), ""),
634                text: js_string(p.get("text"), ""),
635            })
636        },
637    );
638    add(
639        "replace",
640        "Replace an exact string in a file. old must match exactly once unless all is true. Prefer this for edits.",
641        json!({
642            "path": { "type": "STRING", "description": "File relative to /repository" },
643            "old": { "type": "STRING", "description": "Exact text to find" },
644            "new": { "type": "STRING", "description": "Replacement text" },
645            "all": { "type": "BOOLEAN", "description": "Replace every match" },
646        }),
647        &["path", "old", "new"],
648        |p| {
649            MachineTool::File(FileTool::Replace {
650                path: js_string(p.get("path"), ""),
651                old: js_string(p.get("old"), ""),
652                new: js_string(p.get("new"), ""),
653                all: present(p.get("all")).map(truthy),
654            })
655        },
656    );
657    add(
658        "insert",
659        "Insert text after a line number. 0 inserts at the top. Read the file first.",
660        json!({
661            "path": { "type": "STRING", "description": "File relative to /repository" },
662            "after": { "type": "NUMBER", "description": "Line to insert after" },
663            "text": { "type": "STRING", "description": "Text to insert" },
664        }),
665        &["path", "after", "text"],
666        |p| {
667            MachineTool::File(FileTool::Insert {
668                path: js_string(p.get("path"), ""),
669                after: js_number(p.get("after")),
670                text: js_string(p.get("text"), ""),
671            })
672        },
673    );
674    add(
675        "remove",
676        "Delete lines start through end, inclusive. Read the file first.",
677        json!({
678            "path": { "type": "STRING", "description": "File relative to /repository" },
679            "start": { "type": "NUMBER", "description": "First line" },
680            "end": { "type": "NUMBER", "description": "Last line" },
681        }),
682        &["path", "start", "end"],
683        |p| {
684            MachineTool::File(FileTool::Remove {
685                path: js_string(p.get("path"), ""),
686                start: js_number(p.get("start")),
687                end: js_number(p.get("end")),
688            })
689        },
690    );
691
692    add(
693        "processes",
694        "List running processes with their CPU right now, memory, running time, command and listening ports, plus the machine's CPU load, memory and free disk. Default: the 25 busiest by CPU.",
695        json!({
696            "sort": { "type": "STRING", "enum": ["cpu", "memory"], "description": "cpu or memory, default cpu" },
697            "limit": { "type": "NUMBER", "description": "How many to list, default 25" },
698            "filter": { "type": "STRING", "description": "Only commands containing this text" },
699        }),
700        &[],
701        |p| {
702            MachineTool::Process(ProcessTool::Processes {
703                sort: match p.get("sort").and_then(Value::as_str) {
704                    Some("memory") => Some(ProcessSort::Memory),
705                    Some("cpu") => Some(ProcessSort::Cpu),
706                    _ => None,
707                },
708                limit: optional_number(p, "limit"),
709                filter: optional_text(p, "filter"),
710            })
711        },
712    );
713    add(
714        "kill",
715        "Stop one of your processes. TERM asks it to exit, KILL forces it. The machine's own processes, including the desktop's browser, can't be stopped.",
716        json!({
717            "pid": { "type": "NUMBER", "description": "Process id from processes" },
718            "signal": { "type": "STRING", "enum": ["TERM", "KILL"], "description": "TERM (default) or KILL" },
719        }),
720        &["pid"],
721        |p| {
722            MachineTool::Process(ProcessTool::Kill {
723                pid: js_number(p.get("pid")),
724                signal: match p.get("signal").and_then(Value::as_str) {
725                    Some("KILL") => Some(ProcessSignal::Kill),
726                    Some("TERM") => Some(ProcessSignal::Term),
727                    _ => None,
728                },
729            })
730        },
731    );
732
733    tools.push(tool(
734        "exec",
735        "Run a Bash command as the agent user in /repository. Each call is a new shell: cd, exported variables and activated environments don't carry over, and there's no input or terminal. Output comes back when the command exits, and nothing shows on screen; to let people watch a command run, open a terminal with it instead. Start servers and GUI apps in the background with & (or nohup ... &) so they keep running; a timeout stops everything the command started. GUI apps open as desktop windows.",
736        json!({
737            "type": "OBJECT",
738            "properties": {
739                "command": { "type": "STRING", "description": "Bash command" },
740                "timeoutMs": { "type": "NUMBER", "description": "Timeout in ms, default 120000; pass more for installs and builds" },
741            },
742            "required": ["command"],
743        }),
744        move |params: Value| exec(js_string(params.get("command"), ""), optional_number(&params, "timeoutMs")),
745    ));
746    tools
747}
748
749/// `use_desktop`'s result when the person chose not to make a repository for it.
750pub const DESKTOP_DECLINED: &str =
751    "They chose not to use a computer for this. Do it without one if you can.";
752
753const DESKTOP_CAPTURE: &str = "Everything it captures is attached to the chat for people to see, and comes back to you too. Set video to record the whole job as a captioned video, for when someone asks to see it done. Slower and costlier than the other tools; use it only when the screen matters.";
754
755/// The `use_desktop` tool for a Parrot chat: a desktop agent does a job on the
756/// repository's machine. Without a repository it also takes `name`, what to call
757/// the repository the person is asked to make for it.
758pub fn desktop_tool(repository: Option<&Repository>) -> Function {
759    let mut properties = json!({
760        "goal": { "type": "STRING", "description": "What the desktop agent should do, in full, with what to capture" },
761        "video": { "type": "BOOLEAN", "description": "Record the whole job as a captioned video" },
762    });
763    if repository.is_some() {
764        return Function {
765            name: "use_desktop".to_string(),
766            description: Some(format!(
767                "Do something on the repository's desktop that needs a screen, like using a website. A desktop agent does it and reports back. {DESKTOP_CAPTURE}"
768            )),
769            parameters: serde_json::from_value::<Schema>(
770                json!({ "type": "OBJECT", "properties": properties, "required": ["goal"] }),
771            )
772            .expect("tool schemas are valid"),
773            default: None,
774            example: None,
775            behavior: None,
776        };
777    }
778    properties["name"] = json!({ "type": "STRING", "description": "What to call the repository this makes: two to four words about the task, like eBay Switch search" });
779    Function {
780        name: "use_desktop".to_string(),
781        description: Some(format!(
782            "Do something on a computer that needs a screen, like using a website. This chat has no computer yet, so the person is asked first to make a repository for it: a Linux machine with a desktop. If they agree, a desktop agent does it and reports back; if they don't, do that request without a computer. {DESKTOP_CAPTURE}"
783        )),
784        parameters: serde_json::from_value::<Schema>(
785            json!({ "type": "OBJECT", "properties": properties, "required": ["goal", "name"] }),
786        )
787        .expect("tool schemas are valid"),
788        default: None,
789        example: None,
790        behavior: None,
791    }
792}
793
794/// What Termite charges, in dollars.
795#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
796#[serde(rename_all = "camelCase")]
797pub struct Pricing {
798    /// A running machine, per hour.
799    pub machine_per_hour: f64,
800    /// A repository's stored files, per GB a month.
801    pub storage_per_gb_month: f64,
802}
803
804/// Termite's current prices. Anyone can read them, signed in or not.
805pub async fn pricing() -> Result<Pricing> {
806    let response = crate::http::client()
807        .get(format!("{}/termite/pricing", super::get_url()))
808        .send()
809        .await?;
810    let json: Value = crate::http::ok(response).await?.json().await?;
811    Ok(Pricing {
812        machine_per_hour: js_number(json.get("machinePerHour")),
813        storage_per_gb_month: js_number(json.get("storagePerGbMonth")),
814    })
815}
816
817/// `'called' | 'crashed' | 'skipped'` in the TypeScript SDK.
818#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
819#[serde(rename_all = "lowercase")]
820pub enum WakeReason {
821    Called,
822    Crashed,
823    Skipped,
824}
825
826/// One time a repository woke its machine agent: its code ran wake.sh (`called`),
827/// entry.sh crashed (`crashed`), or the hourly limit left it out (`skipped`).
828#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
829pub struct Wake {
830    pub id: String,
831    pub reason: WakeReason,
832    /// What the agent was told: wake.sh's prompt, or how entry.sh ended.
833    pub prompt: String,
834    pub started: DateTime<Utc>,
835    /// When the woken run ended, or None while it works.
836    pub finished: Option<DateTime<Utc>>,
837    pub ok: bool,
838    /// What the agent said when it finished, or why it stopped.
839    pub answer: String,
840}
841
842impl Wake {
843    pub fn from_json(json: &Value) -> Wake {
844        Wake {
845            id: js_string(json.get("id"), "undefined"),
846            reason: match json["reason"].as_str() {
847                Some("crashed") => WakeReason::Crashed,
848                Some("skipped") => WakeReason::Skipped,
849                _ => WakeReason::Called,
850            },
851            prompt: js_string(json.get("prompt"), ""),
852            started: crate::tickets::parse_date(&json["started"]).unwrap_or_default(),
853            finished: if truthy(&json["finished"]) {
854                crate::tickets::parse_date(&json["finished"])
855            } else {
856                None
857            },
858            ok: truthy(&json["ok"]),
859            answer: js_string(json.get("answer"), ""),
860        }
861    }
862}
863
864/// The `opts` argument of the machine calls that take only a group.
865#[derive(Debug, Clone, Default)]
866pub struct GroupOptions {
867    pub group: Option<Group>,
868}
869
870fn authorized(
871    request: reqwest::RequestBuilder,
872    authorization: &CredentialsOrApiKey,
873    group: Option<&Group>,
874) -> reqwest::RequestBuilder {
875    let request = request.header(
876        "Authorization",
877        match authorization {
878            CredentialsOrApiKey::Credentials(credentials) => format!("Token {}", credentials.token),
879            CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
880        },
881    );
882    match group {
883        Some(group) => request.header("Group", &group.id),
884        None => request,
885    }
886}
887
888/// The times a repository woke its agent, newest first.
889pub async fn wakes(
890    authorization: &CredentialsOrApiKey,
891    repository: u64,
892    query: PageQuery,
893    opts: GroupOptions,
894) -> Result<Vec<Wake>> {
895    let response = authorized(
896        crate::http::client().get(format!(
897            "{}/termite/repositories/{repository}/wakes?cursor={}&max={}",
898            super::get_url(),
899            query.cursor,
900            query.max
901        )),
902        authorization,
903        opts.group.as_ref(),
904    )
905    .send()
906    .await?;
907    let json: Value = crate::http::ok(response).await?.json().await?;
908    Ok(json
909        .as_array()
910        .into_iter()
911        .flatten()
912        .map(Wake::from_json)
913        .collect())
914}
915
916struct Machine {
917    windows: HashMap<u64, Window>,
918    files: HashMap<u64, FilesState>,
919    status: MachineStatus,
920    error: String,
921    name: String,
922    private: bool,
923    private_reason: String,
924}
925
926struct MachineState {
927    machine: u64,
928    repository: u64,
929    state: Mutex<Machine>,
930    hooks: Mutex<Arc<dyn MachineRoomHooks>>,
931    calls: Mutex<HashMap<String, oneshot::Sender<Result<Value>>>>,
932}
933
934fn lock<T>(mutex: &Mutex<T>) -> MutexGuard<'_, T> {
935    mutex.lock().unwrap_or_else(PoisonError::into_inner)
936}
937
938/// `{ code, stdout, stderr }` in the TypeScript SDK: how a command ended.
939#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
940pub struct ExecResult {
941    pub code: i64,
942    pub stdout: String,
943    pub stderr: String,
944}
945
946/// The `opts` argument of `exec`.
947#[derive(Debug, Clone, Copy, Default)]
948pub struct ExecOptions {
949    pub timeout_ms: Option<u64>,
950}
951
952/// The `opts` argument of `MachineRoom::start`.
953#[derive(Default)]
954pub struct StartOptions {
955    pub group: Option<Group>,
956    pub hooks: Option<Arc<dyn MachineRoomHooks>>,
957    pub private: Option<bool>,
958}
959
960/// The `opts` argument of `MachineRoom::connect` and `MachineRoom::join`
961/// (which takes no group).
962#[derive(Default)]
963pub struct MachineOptions {
964    pub group: Option<Group>,
965    pub hooks: Option<Arc<dyn MachineRoomHooks>>,
966}
967
968/// `{ id } | { reference }` in the TypeScript SDK: a machine by id, or by its
969/// `termite:machine:{id}` reference.
970#[derive(Debug, Clone, PartialEq, Eq)]
971pub enum MachineTarget {
972    Id { id: u64 },
973    Reference { reference: String },
974}
975
976/// `{ on, reason }` in the TypeScript SDK.
977#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
978pub struct PrivateState {
979    pub on: bool,
980    pub reason: String,
981}
982
983#[derive(Clone)]
984pub struct MachineRoom {
985    page: PageRoom,
986    inner: Arc<MachineState>,
987}
988
989impl Deref for MachineRoom {
990    type Target = PageRoom;
991    fn deref(&self) -> &PageRoom {
992        &self.page
993    }
994}
995
996impl MachineRoom {
997    fn create(room: &Room, hooks: Arc<dyn MachineRoomHooks>, state: &Value) -> MachineRoom {
998        let page_hooks: Arc<dyn BrowserRoomHooks> = hooks.clone();
999        let page = PageRoom::create(
1000            room,
1001            page_hooks,
1002            state,
1003            Some(DESKTOP_TOOLS.iter().map(|kind| kind.to_string()).collect()),
1004        );
1005        let machine = MachineRoom {
1006            page,
1007            inner: Arc::new(MachineState {
1008                machine: js_number(Some(&state["machine"]["id"])) as u64,
1009                repository: js_number(Some(&state["machine"]["repository"])) as u64,
1010                state: Mutex::new(Machine {
1011                    windows: HashMap::new(),
1012                    files: HashMap::new(),
1013                    status: MachineStatus::Booting,
1014                    error: String::new(),
1015                    name: String::new(),
1016                    private: false,
1017                    private_reason: String::new(),
1018                }),
1019                hooks: Mutex::new(hooks),
1020                calls: Mutex::new(HashMap::new()),
1021            }),
1022        };
1023        machine.hydrate(state);
1024        machine
1025    }
1026
1027    fn machine_state(&self) -> MutexGuard<'_, Machine> {
1028        lock(&self.inner.state)
1029    }
1030
1031    fn machine_hooks(&self) -> Arc<dyn MachineRoomHooks> {
1032        lock(&self.inner.hooks).clone()
1033    }
1034
1035    /// The machine id, the number `connect` takes.
1036    pub fn machine(&self) -> u64 {
1037        self.inner.machine
1038    }
1039
1040    pub fn repository(&self) -> u64 {
1041        self.inner.repository
1042    }
1043
1044    pub fn windows(&self) -> HashMap<u64, Window> {
1045        self.machine_state().windows.clone()
1046    }
1047
1048    /// Each Files window's folder and view, by window id.
1049    pub fn files(&self) -> HashMap<u64, FilesState> {
1050        self.machine_state().files.clone()
1051    }
1052
1053    pub fn status(&self) -> MachineStatus {
1054        self.machine_state().status
1055    }
1056
1057    /// Why the machine failed, when it did.
1058    pub fn error(&self) -> String {
1059        self.machine_state().error.clone()
1060    }
1061
1062    /// The repository's name, so a guest who joined by code knows what it is.
1063    pub fn name(&self) -> String {
1064        self.machine_state().name.clone()
1065    }
1066
1067    /// Its connections go out from a residential address, billed per GB to whoever pays for the machine.
1068    pub fn private(&self) -> bool {
1069        self.machine_state().private
1070    }
1071
1072    /// Why private is off when it couldn't turn on or stay on, like a payer out of balance.
1073    pub fn private_reason(&self) -> String {
1074        self.machine_state().private_reason.clone()
1075    }
1076
1077    /// Apply a connection snapshot `{ machine, bootstrap, cursor, windows }`.
1078    pub fn hydrate(&self, state: &Value) {
1079        self.page.apply_control(&state["control"]);
1080        let mut machine = self.machine_state();
1081        if let Ok(status) = serde_json::from_value(state["machine"]["status"].clone()) {
1082            machine.status = status;
1083        }
1084        if state["machine"].is_object() {
1085            machine.error = js_string(state["machine"].get("error"), "");
1086            machine.name = js_string(state["machine"].get("name"), "");
1087        }
1088        if let Some(windows) = state["windows"].as_array() {
1089            machine.windows = windows
1090                .iter()
1091                .map(Window::from_json)
1092                .map(|window| (window.id, window))
1093                .collect();
1094        }
1095        if let Some(files) = state["files"].as_array() {
1096            machine.files = files
1097                .iter()
1098                .map(|row| {
1099                    (
1100                        js_number(row.get("window")) as u64,
1101                        FilesState::from_json(row),
1102                    )
1103                })
1104                .collect();
1105        }
1106        if truthy(&state["private"]) {
1107            machine.private = truthy(&state["private"]["on"]);
1108            machine.private_reason = js_string(state["private"].get("reason"), "");
1109        }
1110    }
1111
1112    pub fn watch(&self, hooks: Arc<dyn MachineRoomHooks>) {
1113        *lock(&self.inner.hooks) = hooks.clone();
1114        self.page.watch(hooks);
1115    }
1116
1117    pub async fn invoke_tool(&self, tool: &MachineTool) -> Result<String> {
1118        if let MachineTool::Desktop(tool) = tool
1119            && DESKTOP_TOOLS.contains(&tool.kind())
1120        {
1121            return self.page.invoke_tool(tool).await;
1122        }
1123        let result = self
1124            .call(json!({ "kind": "tool", "tool": tool }), CALL_MS)
1125            .await?;
1126        Ok(match result {
1127            Value::Null => String::new(),
1128            Value::String(result) => result,
1129            result => result.to_string(),
1130        })
1131    }
1132
1133    /// Run a shell command as `agent` in /repository with DISPLAY=:0, so GUI apps open as desktop windows.
1134    pub async fn exec(&self, command: &str, opts: ExecOptions) -> Result<ExecResult> {
1135        let timeout_ms = opts.timeout_ms.unwrap_or(EXEC_MS);
1136        let result = self
1137            .call(
1138                json!({ "kind": "exec", "command": command, "timeoutMs": timeout_ms }),
1139                timeout_ms + 15_000,
1140            )
1141            .await?;
1142        Ok(ExecResult {
1143            code: match result.get("code") {
1144                None | Some(Value::Null) => -1,
1145                code => js_number(code) as i64,
1146            },
1147            stdout: js_string(result.get("stdout"), ""),
1148            stderr: js_string(result.get("stderr"), ""),
1149        })
1150    }
1151
1152    /// Size the machine's desktop to this seat's screen, clamped to `VIEWPORT`. Only the controller can.
1153    pub async fn set_viewport(&self, width: f64, height: f64) -> Result<()> {
1154        let size = clamp_viewport(Viewport { width, height });
1155        self.call(
1156            json!({ "kind": "viewport", "width": size.width, "height": size.height }),
1157            CALL_MS,
1158        )
1159        .await?;
1160        Ok(())
1161    }
1162
1163    /// Open a file in an app on the machine, for everyone to see: text in nano inside an
1164    /// xterm, anything else with an installed opener. Only the controller can.
1165    pub async fn open(&self, path: &str) -> Result<()> {
1166        self.call(json!({ "kind": "open", "path": path }), CALL_MS)
1167            .await?;
1168        Ok(())
1169    }
1170
1171    /// Put a Files window on a folder and view for every seat. Only the controller can.
1172    pub async fn set_files(&self, window: u64, files: &FilesState) -> Result<()> {
1173        self.call(
1174            json!({ "kind": "files", "window": window, "path": files.path, "view": files.view }),
1175            CALL_MS,
1176        )
1177        .await?;
1178        Ok(())
1179    }
1180
1181    /// Save a new revision and shut down. The room closes afterwards.
1182    pub async fn stop(&self) -> Result<()> {
1183        match self.call(json!({ "kind": "stop" }), STOP_MS).await {
1184            Ok(_) => Ok(()),
1185            // The machine announces it closed before it answers the stop itself.
1186            Err(_) if self.status() == MachineStatus::Stopped => Ok(()),
1187            Err(error) => Err(error),
1188        }
1189    }
1190
1191    async fn call(&self, call: Value, timeout_ms: u64) -> Result<Value> {
1192        let id = uuid::Uuid::new_v4().to_string();
1193        let (resolve, result) = oneshot::channel();
1194        lock(&self.inner.calls).insert(id.clone(), resolve);
1195        self.post(&json!({ "event": "machine-call", "data": { "id": id, "call": call } }));
1196        match tokio::time::timeout(Duration::from_millis(timeout_ms), result).await {
1197            Ok(Ok(result)) => result,
1198            Ok(Err(_)) => Err(Error::Message("Machine closed.".to_string())),
1199            Err(_) => {
1200                lock(&self.inner.calls).remove(&id);
1201                Err(Error::Message("Machine call timed out.".to_string()))
1202            }
1203        }
1204    }
1205
1206    pub fn parrot_tools(&self) -> Vec<Tool> {
1207        let invoking = self.clone();
1208        let executing = self.clone();
1209        parrot_tools(
1210            Arc::new(move |tool| {
1211                let room = invoking.clone();
1212                Box::pin(async move { room.invoke_tool(&tool).await })
1213            }),
1214            Arc::new(move |command, timeout_ms| {
1215                let room = executing.clone();
1216                Box::pin(async move {
1217                    let result = room
1218                        .exec(
1219                            &command,
1220                            ExecOptions {
1221                                timeout_ms: timeout_ms.map(|ms| ms as u64),
1222                            },
1223                        )
1224                        .await?;
1225                    Ok(serde_json::to_string(&result)?)
1226                })
1227            }),
1228        )
1229    }
1230
1231    pub fn handle_event(&self, packet: &Value) -> bool {
1232        let data = &packet["data"];
1233        let hooks = self.machine_hooks();
1234        match packet["event"].as_str().unwrap_or_default() {
1235            "machine-status" => {
1236                if let Ok(status) = serde_json::from_value(data["status"].clone()) {
1237                    self.machine_state().status = status;
1238                }
1239                hooks.on_status(self);
1240                true
1241            }
1242            "machine-window" => {
1243                if !truthy(&data["window"]) {
1244                    return true;
1245                }
1246                let window = Window::from_json(&data["window"]);
1247                self.machine_state()
1248                    .windows
1249                    .insert(window.id, window.clone());
1250                hooks.on_window(self, &window);
1251                true
1252            }
1253            "machine-window-closed" => {
1254                let id = js_number(data.get("id")) as u64;
1255                {
1256                    let mut machine = self.machine_state();
1257                    machine.windows.remove(&id);
1258                    machine.files.remove(&id);
1259                }
1260                hooks.on_window_closed(self, id);
1261                true
1262            }
1263            "machine-files" => {
1264                let window = js_number(data.get("window")) as u64;
1265                let files = FilesState::from_json(data);
1266                self.machine_state().files.insert(window, files.clone());
1267                hooks.on_files(self, window, &files);
1268                true
1269            }
1270            "machine-private" => {
1271                {
1272                    let mut machine = self.machine_state();
1273                    machine.private = truthy(&data["on"]);
1274                    machine.private_reason = js_string(data.get("reason"), "");
1275                }
1276                hooks.on_private(self);
1277                true
1278            }
1279            "machine-agent-step" => {
1280                if let Ok(step) = serde_json::from_value::<AgentStep>(data.clone()) {
1281                    hooks.on_agent_step(self, &step);
1282                }
1283                true
1284            }
1285            "machine-result" => {
1286                let Some(id) = data["id"].as_str() else {
1287                    return true;
1288                };
1289                let Some(pending) = lock(&self.inner.calls).remove(id) else {
1290                    return true;
1291                };
1292                let _ = pending.send(if truthy(&data["error"]) {
1293                    Err(Error::Message(js_string(data.get("error"), "")))
1294                } else {
1295                    Ok(data["result"].clone())
1296                });
1297                true
1298            }
1299            "machine-closed" => {
1300                {
1301                    let mut machine = self.machine_state();
1302                    if let Ok(status) = serde_json::from_value(data["status"].clone()) {
1303                        machine.status = status;
1304                    }
1305                    machine.error = js_string(data.get("error"), "");
1306                }
1307                hooks.on_status(self);
1308                for (_, pending) in lock(&self.inner.calls).drain() {
1309                    let _ = pending.send(Err(Error::Message("Machine closed.".to_string())));
1310                }
1311                self.page
1312                    .handle_event(&json!({ "event": "browser-closed", "data": {} }))
1313            }
1314            _ => self.page.handle_event(packet),
1315        }
1316    }
1317
1318    /// Boot the repository's machine, or return the one already live, and connect to it.
1319    /// `private` sends its connections out from a residential address, billed per GB to
1320    /// whoever pays for the machine; on a live machine it switches it.
1321    pub async fn start(
1322        authorization: &CredentialsOrApiKey,
1323        repository: u64,
1324        opts: StartOptions,
1325    ) -> Result<(MachineRoom, Presence)> {
1326        let body = match opts.private {
1327            Some(private) => json!({ "private": private }),
1328            None => json!({}),
1329        };
1330        let response = authorized(
1331            crate::http::client().post(format!(
1332                "{}/termite/repositories/{repository}/machine",
1333                super::get_url()
1334            )),
1335            authorization,
1336            opts.group.as_ref(),
1337        )
1338        .json(&body)
1339        .send()
1340        .await?;
1341        let json: Value = crate::http::ok(response).await?.json().await?;
1342        MachineRoom::connect(
1343            authorization,
1344            &MachineTarget::Id {
1345                id: js_number(json.get("id")) as u64,
1346            },
1347            MachineOptions {
1348                group: opts.group,
1349                hooks: opts.hooks,
1350            },
1351        )
1352        .await
1353    }
1354
1355    /// Save and shut down a repository's machine without joining its room. For its owner or group members.
1356    pub async fn shutdown(
1357        authorization: &CredentialsOrApiKey,
1358        repository: u64,
1359        opts: GroupOptions,
1360    ) -> Result<()> {
1361        let response = authorized(
1362            crate::http::client().post(format!(
1363                "{}/termite/repositories/{repository}/machine/stop",
1364                super::get_url()
1365            )),
1366            authorization,
1367            opts.group.as_ref(),
1368        )
1369        .json(&json!({}))
1370        .send()
1371        .await?;
1372        crate::http::ok(response).await?;
1373        Ok(())
1374    }
1375
1376    /// Turn private on or off for a repository's live machine, for its owner or group members.
1377    /// Resolves to the machine's private state and, when it couldn't turn on, why.
1378    pub async fn set_private(
1379        authorization: &CredentialsOrApiKey,
1380        repository: u64,
1381        on: bool,
1382        opts: GroupOptions,
1383    ) -> Result<PrivateState> {
1384        let response = authorized(
1385            crate::http::client().post(format!(
1386                "{}/termite/repositories/{repository}/machine/private",
1387                super::get_url()
1388            )),
1389            authorization,
1390            opts.group.as_ref(),
1391        )
1392        .json(&json!({ "on": on }))
1393        .send()
1394        .await?;
1395        let json: Value = crate::http::ok(response).await?.json().await?;
1396        Ok(PrivateState {
1397            on: truthy(&json["on"]),
1398            reason: js_string(json.get("reason"), ""),
1399        })
1400    }
1401
1402    /// Connect to a live machine by id, or by its `termite:machine:{id}` reference.
1403    pub async fn connect(
1404        authorization: &CredentialsOrApiKey,
1405        target: &MachineTarget,
1406        opts: MachineOptions,
1407    ) -> Result<(MachineRoom, Presence)> {
1408        MachineRoom::open_room(
1409            Authorization::Server {
1410                authorization: authorization.clone(),
1411                server: match target {
1412                    MachineTarget::Id { id } => format!("termite:machine:{id}"),
1413                    MachineTarget::Reference { reference } => reference.clone(),
1414                },
1415                group: opts.group.as_ref().map(|group| group.id.clone()),
1416            },
1417            opts.hooks.unwrap_or_else(|| Arc::new(())),
1418        )
1419        .await
1420    }
1421
1422    /// Join a machine someone shared with an access code.
1423    pub async fn join(
1424        authorization: &CredentialsOrApiKey,
1425        access_code: &str,
1426        opts: MachineOptions,
1427    ) -> Result<(MachineRoom, Presence)> {
1428        MachineRoom::open_room(
1429            Authorization::AccessCode {
1430                authorization: authorization.clone(),
1431                access_code: access_code.to_string(),
1432            },
1433            opts.hooks.unwrap_or_else(|| Arc::new(())),
1434        )
1435        .await
1436    }
1437
1438    async fn open_room(
1439        auth: Authorization,
1440        hooks: Arc<dyn MachineRoomHooks>,
1441    ) -> Result<(MachineRoom, Presence)> {
1442        let machine_hooks = Arc::new(MachineHooks {
1443            room: Mutex::new(None),
1444            hooks,
1445        });
1446        let me = connect_server(
1447            auth,
1448            &format!("{}/termite/machine/live", super::get_url()),
1449            machine_hooks.clone(),
1450        )
1451        .await?;
1452        let room = machine_hooks
1453            .room()
1454            .ok_or_else(|| Error::Message("Room not found".to_string()))?;
1455        room.emit_presence();
1456        Ok((room, me))
1457    }
1458}
1459
1460struct MachineHooks {
1461    room: Mutex<Option<MachineRoom>>,
1462    hooks: Arc<dyn MachineRoomHooks>,
1463}
1464
1465impl MachineHooks {
1466    fn room(&self) -> Option<MachineRoom> {
1467        lock(&self.room).clone()
1468    }
1469}
1470
1471impl Hooks for MachineHooks {
1472    fn create_room(&self, room: &Room, state: &Value) {
1473        *lock(&self.room) = Some(MachineRoom::create(room, self.hooks.clone(), state));
1474    }
1475
1476    fn on_presence(&self, _room: &Room) {
1477        if let Some(room) = self.room() {
1478            room.emit_presence();
1479        }
1480    }
1481
1482    fn on_connection(&self, _room: &Room, state: &Value) {
1483        let Some(room) = self.room() else {
1484            return;
1485        };
1486        if let Ok(bootstrap) = serde_json::from_value::<BootstrapMeta>(state["bootstrap"].clone()) {
1487            room.web().ingest_bootstrap(bootstrap);
1488        }
1489        if let Ok(cursor) = serde_json::from_value::<HtmlPointer>(state["cursor"].clone()) {
1490            room.page.set_cursor(cursor.clone());
1491            room.machine_hooks().on_cursor(&room.page, &cursor);
1492        }
1493        room.hydrate(state);
1494    }
1495
1496    fn on_event(&self, _room: &Room, packet: &Value) -> bool {
1497        self.room().is_some_and(|room| room.handle_event(packet))
1498    }
1499
1500    fn on_closed(&self, _room: &Room, _reason: Option<&str>) {
1501        if let Some(room) = self.room() {
1502            room.emit_closed();
1503        }
1504    }
1505}