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