Skip to main content

fauna_api/termite/
os.rs

1//! A live machine: one running boot of a Repository. Its page is the machine's desktop, one
2//! HTML page that is the whole OS, streamed to every seat. Pointer and keyboard input, window
3//! tools, file tools, exec, and stop ride the same socket.
4
5use std::collections::HashMap;
6use std::ops::Deref;
7use std::sync::{Arc, Mutex, MutexGuard, PoisonError};
8use std::time::Duration;
9
10use chrono::{DateTime, Utc};
11use futures_util::future::BoxFuture;
12use serde::{Deserialize, Serialize};
13use serde_json::{Map, Value, json};
14use tokio::sync::oneshot;
15
16use super::spec::Spec;
17use super::versioning::Repository;
18use crate::authentification::CredentialsOrApiKey;
19use crate::billing::PageQuery;
20use crate::error::{Error, Result};
21use crate::groups::Group;
22use crate::js::{js_number, js_string, present};
23use crate::marmot::web::{HtmlPointer, WebRoom, WebRoomHooks};
24use crate::parrot::generative::{Function, Tool, Usage, tool};
25use crate::shared::schema::{ObjectSchema, Schema};
26use crate::shared::server::{Authorization, Hooks, Presence, Room, connect as connect_server};
27
28#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
29#[serde(rename_all = "lowercase")]
30pub enum MouseButton {
31    Left,
32    Right,
33    Middle,
34}
35
36/// `{ x, y }` in the TypeScript SDK.
37#[derive(Debug, Clone, Copy, Default, PartialEq, Serialize, Deserialize)]
38pub struct Point {
39    pub x: f64,
40    pub y: f64,
41}
42
43/// `'web' | 'files' | 'file' | 'terminal'` in the TypeScript SDK.
44#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
45#[serde(rename_all = "lowercase")]
46pub enum WindowApp {
47    Web,
48    Files,
49    File,
50    Terminal,
51}
52
53/// `'files' | 'lines' | 'count'` in the TypeScript SDK.
54#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
55#[serde(rename_all = "lowercase")]
56pub enum GrepOutput {
57    Files,
58    Lines,
59    Count,
60}
61
62/// `'cpu' | 'memory'` in the TypeScript SDK.
63#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
64#[serde(rename_all = "lowercase")]
65pub enum ProcessSort {
66    Cpu,
67    Memory,
68}
69
70/// `'TERM' | 'KILL'` in the TypeScript SDK.
71#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
72#[serde(rename_all = "UPPERCASE")]
73pub enum ProcessSignal {
74    Term,
75    Kill,
76}
77
78/// `'private' | 'public'` in the TypeScript SDK.
79#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
80#[serde(rename_all = "lowercase")]
81pub enum InternetMode {
82    Private,
83    Public,
84}
85
86/// A key going down or up, by the name a browser's `KeyboardEvent.key` gives it ('a', 'A',
87/// 'Shift', 'Enter').
88#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
89pub struct KeyStroke {
90    pub key: String,
91    pub down: bool,
92}
93
94/// Everything a seat or an agent does on a machine. Positions are desktop pixels. Paths are
95/// relative to /repository, and `/` is the repository root.
96#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
97#[serde(
98    tag = "kind",
99    rename_all = "camelCase",
100    rename_all_fields = "camelCase"
101)]
102pub enum MachineTool {
103    Move {
104        x: f64,
105        y: f64,
106    },
107    /// `count` clicks in a row (2 is a double click). A click on the same spot right after
108    /// another continues its run, the way a person's quick second click does.
109    Click {
110        #[serde(default, skip_serializing_if = "Option::is_none")]
111        x: Option<f64>,
112        #[serde(default, skip_serializing_if = "Option::is_none")]
113        y: Option<f64>,
114        #[serde(default, skip_serializing_if = "Option::is_none")]
115        down_ms: Option<f64>,
116        #[serde(default, skip_serializing_if = "Option::is_none")]
117        button: Option<MouseButton>,
118        #[serde(default, skip_serializing_if = "Option::is_none")]
119        count: Option<f64>,
120    },
121    Drag {
122        to: Point,
123        #[serde(default, skip_serializing_if = "Option::is_none")]
124        from: Option<Point>,
125        #[serde(default, skip_serializing_if = "Option::is_none")]
126        down_ms: Option<f64>,
127    },
128    Scroll {
129        #[serde(default, skip_serializing_if = "Option::is_none")]
130        delta_x: Option<f64>,
131        #[serde(default, skip_serializing_if = "Option::is_none")]
132        delta_y: Option<f64>,
133    },
134    Type {
135        text: String,
136    },
137    /// A person's own input, sent as it happens: a button goes down and up where the pointer
138    /// is, `pointer` moves it while a button is down (a drag), the wheel turns at a point, and
139    /// keys go down and up in order. Each lands at once; agents use the tools above.
140    Press {
141        x: f64,
142        y: f64,
143        #[serde(default, skip_serializing_if = "Option::is_none")]
144        button: Option<MouseButton>,
145    },
146    Pointer {
147        x: f64,
148        y: f64,
149    },
150    Release {
151        x: f64,
152        y: f64,
153        #[serde(default, skip_serializing_if = "Option::is_none")]
154        button: Option<MouseButton>,
155    },
156    Wheel {
157        x: f64,
158        y: f64,
159        delta_x: f64,
160        delta_y: f64,
161    },
162    Keys {
163        strokes: Vec<KeyStroke>,
164    },
165    Windows,
166    Focus {
167        window: f64,
168    },
169    Place {
170        window: f64,
171        x: f64,
172        y: f64,
173    },
174    Resize {
175        window: f64,
176        width: f64,
177        height: f64,
178    },
179    Close {
180        window: f64,
181    },
182    /// Load a Web window's page again, after its files change. Previews follow their file on their own.
183    Reload {
184        window: f64,
185    },
186    /// A web window at `url`; a files window at `path` (a folder of /repository); the file at
187    /// `path` in an editor (text and code) or a preview (images, PDFs, video, audio), which
188    /// follows the file as it changes; or a terminal, running `command` in view and staying open
189    /// at a prompt when it ends.
190    Open {
191        app: WindowApp,
192        #[serde(default, skip_serializing_if = "Option::is_none")]
193        url: Option<String>,
194        #[serde(default, skip_serializing_if = "Option::is_none")]
195        path: Option<String>,
196        #[serde(default, skip_serializing_if = "Option::is_none")]
197        command: Option<String>,
198    },
199    /// A chord like ['ctrl', 's']. Focuses `window` first when given.
200    Key {
201        keys: Vec<String>,
202        #[serde(default, skip_serializing_if = "Option::is_none")]
203        window: Option<f64>,
204    },
205    /// The page in Web window `window`, or the focused one: `{ url, html }` as JSON, the HTML
206    /// trimmed to the body without styles, scripts and SVG.
207    PageHtml {
208        #[serde(default, skip_serializing_if = "Option::is_none")]
209        window: Option<f64>,
210    },
211    /// Runs `script` in the page of Web window `window`, or the focused one: its result as text,
212    /// a string as it is and anything else as JSON.
213    PageScript {
214        script: String,
215        #[serde(default, skip_serializing_if = "Option::is_none")]
216        window: Option<f64>,
217    },
218    List {
219        #[serde(default, skip_serializing_if = "Option::is_none")]
220        path: Option<String>,
221        #[serde(default, skip_serializing_if = "Option::is_none")]
222        pattern: Option<String>,
223    },
224    Grep {
225        pattern: String,
226        #[serde(default, skip_serializing_if = "Option::is_none")]
227        path: Option<String>,
228        #[serde(default, skip_serializing_if = "Option::is_none")]
229        glob: Option<String>,
230        #[serde(default, skip_serializing_if = "Option::is_none")]
231        ignore_case: Option<bool>,
232        #[serde(default, skip_serializing_if = "Option::is_none")]
233        context: Option<f64>,
234        #[serde(default, skip_serializing_if = "Option::is_none")]
235        output: Option<GrepOutput>,
236        #[serde(default, skip_serializing_if = "Option::is_none")]
237        max: Option<f64>,
238    },
239    Read {
240        path: String,
241        #[serde(default, skip_serializing_if = "Option::is_none")]
242        line: Option<f64>,
243        #[serde(default, skip_serializing_if = "Option::is_none")]
244        before: Option<f64>,
245        #[serde(default, skip_serializing_if = "Option::is_none")]
246        after: Option<f64>,
247    },
248    /// The whole file, or with `line`, `text` inserted after that line (0 for the top).
249    Write {
250        path: String,
251        text: String,
252        #[serde(default, skip_serializing_if = "Option::is_none")]
253        line: Option<f64>,
254    },
255    Replace {
256        path: String,
257        old: String,
258        new: String,
259        #[serde(default, skip_serializing_if = "Option::is_none")]
260        all: Option<bool>,
261    },
262    Remove {
263        path: String,
264        start: f64,
265        end: f64,
266    },
267    Processes {
268        #[serde(default, skip_serializing_if = "Option::is_none")]
269        sort: Option<ProcessSort>,
270        #[serde(default, skip_serializing_if = "Option::is_none")]
271        limit: Option<f64>,
272        #[serde(default, skip_serializing_if = "Option::is_none")]
273        filter: Option<String>,
274    },
275    /// Stops only the agent user's own processes, never the machine's or the desktop's.
276    Kill {
277        pid: f64,
278        #[serde(default, skip_serializing_if = "Option::is_none")]
279        signal: Option<ProcessSignal>,
280    },
281    /// How the machine reaches the internet: `private` only from a residential address, billed
282    /// per GB to whoever pays for the machine, or `public` from its own.
283    Internet {
284        mode: InternetMode,
285    },
286    /// Pause, then look again. Costs machine time but no model calls; at most
287    /// `WAIT_MAX_SECONDS` a call.
288    Wait {
289        seconds: f64,
290    },
291}
292
293impl MachineTool {
294    /// Pointer and keyboard input, which the desktop page itself takes.
295    fn is_input(&self) -> bool {
296        matches!(
297            self,
298            MachineTool::Move { .. }
299                | MachineTool::Click { .. }
300                | MachineTool::Drag { .. }
301                | MachineTool::Scroll { .. }
302                | MachineTool::Type { .. }
303                | MachineTool::Press { .. }
304                | MachineTool::Pointer { .. }
305                | MachineTool::Release { .. }
306                | MachineTool::Wheel { .. }
307                | MachineTool::Keys { .. }
308        )
309    }
310}
311
312/// The longest one `wait` pauses.
313pub const WAIT_MAX_SECONDS: u64 = 600;
314
315/// `'app' | 'web' | 'files' | 'preview' | 'terminal' | 'editor'` in the TypeScript SDK.
316#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
317#[serde(rename_all = "lowercase")]
318pub enum WindowKind {
319    App,
320    Web,
321    Files,
322    Preview,
323    Terminal,
324    Editor,
325}
326
327/// Metadata for one desktop window. Its pixels live in the desktop HTML.
328#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
329pub struct Window {
330    /// Same id as the element's data-window and the window tools.
331    pub id: u64,
332    pub kind: WindowKind,
333    /// WM_CLASS for X11 apps ('xmessage'), else the kind.
334    pub app: String,
335    pub title: String,
336    pub x: f64,
337    pub y: f64,
338    pub width: f64,
339    pub height: f64,
340    pub focused: bool,
341}
342
343fn truthy(value: &Value) -> bool {
344    match value {
345        Value::Null => false,
346        Value::Bool(value) => *value,
347        Value::Number(number) => number
348            .as_f64()
349            .is_some_and(|number| number != 0.0 && !number.is_nan()),
350        Value::String(text) => !text.is_empty(),
351        _ => true,
352    }
353}
354
355impl Window {
356    pub fn from_json(json: &Value) -> Window {
357        let kind = match json["kind"].as_str() {
358            Some("web") => WindowKind::Web,
359            Some("files") => WindowKind::Files,
360            Some("preview") => WindowKind::Preview,
361            Some("terminal") => WindowKind::Terminal,
362            Some("editor") => WindowKind::Editor,
363            _ => WindowKind::App,
364        };
365        let kind_name = match kind {
366            WindowKind::App => "app",
367            WindowKind::Web => "web",
368            WindowKind::Files => "files",
369            WindowKind::Preview => "preview",
370            WindowKind::Terminal => "terminal",
371            WindowKind::Editor => "editor",
372        };
373        Window {
374            id: js_number(json.get("id")) as u64,
375            kind,
376            app: js_string(json.get("app"), kind_name),
377            title: js_string(json.get("title"), ""),
378            x: json["x"].as_f64().unwrap_or_default(),
379            y: json["y"].as_f64().unwrap_or_default(),
380            width: json["width"].as_f64().unwrap_or_default(),
381            height: json["height"].as_f64().unwrap_or_default(),
382            focused: truthy(&json["focused"]),
383        }
384    }
385}
386
387/// `'list' | 'cozy'` in the TypeScript SDK.
388#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
389#[serde(rename_all = "lowercase")]
390pub enum FilesView {
391    List,
392    Cozy,
393}
394
395/// The folder and view a Files window is on. The controller sets it; every seat follows.
396#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
397pub struct FilesState {
398    pub path: String,
399    pub view: FilesView,
400}
401
402impl FilesState {
403    pub fn from_json(json: &Value) -> FilesState {
404        FilesState {
405            path: js_string(json.get("path"), ""),
406            view: if json["view"] == "cozy" {
407                FilesView::Cozy
408            } else {
409                FilesView::List
410            },
411        }
412    }
413}
414
415#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
416#[serde(rename_all = "UPPERCASE")]
417pub enum MachineStatus {
418    Booting,
419    Running,
420    Stopping,
421    Stopped,
422    Failed,
423}
424
425#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
426pub struct Viewport {
427    pub width: f64,
428    pub height: f64,
429}
430
431/// `{ min, max }` in the TypeScript SDK.
432#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
433pub struct ViewportBounds {
434    pub min: Viewport,
435    pub max: Viewport,
436}
437
438/// The smallest and largest desktop a machine draws. The largest is the guest's X screen.
439pub const VIEWPORT: ViewportBounds = ViewportBounds {
440    min: Viewport {
441        width: 640.0,
442        height: 400.0,
443    },
444    max: Viewport {
445        width: 2560.0,
446        height: 1600.0,
447    },
448};
449
450/// A desktop size inside `VIEWPORT`, in whole pixels.
451pub fn clamp_viewport(size: Viewport) -> Viewport {
452    Viewport {
453        width: size
454            .width
455            .clamp(VIEWPORT.min.width, VIEWPORT.max.width)
456            .round(),
457        height: size
458            .height
459            .clamp(VIEWPORT.min.height, VIEWPORT.max.height)
460            .round(),
461    }
462}
463
464/// The first byte of an app frame.
465const APP_FRAME: u8 = 1;
466/// Set in an app frame's flags when it covers its whole window.
467const APP_FRAME_KEY: u8 = 1;
468/// An app frame's header: kind, flags, window, seq, the window's width and height, then the
469/// region's x, y, width and height, all big endian.
470const APP_FRAME_HEADER: usize = 22;
471
472/// A picture of part of an X11 app window, which a machine room sends as a binary frame: a JPEG
473/// to draw at (`x`, `y`) in window `window` (its element's `data-xid` in the desktop), which is
474/// `window_width` by `window_height` now. Each window's frames count up in `seq`; a skipped
475/// count means a stale frame was dropped, and the window needs a repaint unless the frame is a
476/// `key` frame, which covers the whole window.
477#[derive(Debug, Clone, PartialEq, Eq)]
478pub struct AppFrame {
479    pub window: u32,
480    pub seq: u32,
481    pub key: bool,
482    pub window_width: u32,
483    pub window_height: u32,
484    pub x: u32,
485    pub y: u32,
486    pub width: u32,
487    pub height: u32,
488    pub jpeg: Vec<u8>,
489}
490
491impl AppFrame {
492    /// A binary frame as an app frame, or `None` when it isn't one.
493    pub fn from_bytes(data: &[u8]) -> Option<AppFrame> {
494        if data.len() < APP_FRAME_HEADER || data[0] != APP_FRAME {
495            return None;
496        }
497        let u32_at =
498            |at: usize| u32::from_be_bytes([data[at], data[at + 1], data[at + 2], data[at + 3]]);
499        let u16_at = |at: usize| u32::from(u16::from_be_bytes([data[at], data[at + 1]]));
500        Some(AppFrame {
501            window: u32_at(2),
502            seq: u32_at(6),
503            key: data[1] & APP_FRAME_KEY != 0,
504            window_width: u16_at(10),
505            window_height: u16_at(12),
506            x: u16_at(14),
507            y: u16_at(16),
508            width: u16_at(18),
509            height: u16_at(20),
510            jpeg: data[APP_FRAME_HEADER..].to_vec(),
511        })
512    }
513}
514
515/// An agent driving the machine. While one does, nobody else can act.
516#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
517pub struct RoomAgent {
518    pub id: String,
519    pub name: String,
520    #[serde(default, skip_serializing_if = "Option::is_none")]
521    pub icon: Option<String>,
522}
523
524impl RoomAgent {
525    pub fn from_json(json: &Value) -> RoomAgent {
526        RoomAgent {
527            id: match &json["id"] {
528                Value::String(id) => id.clone(),
529                id => id.to_string(),
530            },
531            name: match &json["name"] {
532                Value::Null => "Agent".to_string(),
533                Value::String(name) => name.clone(),
534                name => name.to_string(),
535            },
536            icon: json["icon"]
537                .as_str()
538                .filter(|icon| !icon.is_empty())
539                .map(str::to_string),
540        }
541    }
542}
543
544/// Machine room hooks. Every method defaults to a no-op, like the optional members of the
545/// TypeScript `MachineRoomHooks` object; `web` is its nested web hooks.
546pub trait MachineRoomHooks: Send + Sync {
547    /// The desktop's pointer moved or changed shape.
548    fn on_cursor(&self, _room: &MachineRoom, _cursor: &HtmlPointer) {}
549    /// An agent, or a seat through a tool, used the pointer or the keyboard. A person's own
550    /// input as it happens isn't announced; their presence shows it.
551    fn on_tool(&self, _room: &MachineRoom, _tool: &MachineTool) {}
552    fn on_closed(&self, _room: &MachineRoom) {}
553    fn on_presence(&self, _room: &MachineRoom) {}
554    /// Control changed hands, or an agent took or released the machine.
555    fn on_control(&self, _room: &MachineRoom) {}
556    fn web(&self) -> Option<Arc<dyn WebRoomHooks>> {
557        None
558    }
559    /// A window opened, moved, resized, retitled, or changed focus.
560    fn on_window(&self, _room: &MachineRoom, _window: &Window) {}
561    fn on_window_closed(&self, _room: &MachineRoom, _id: u64) {}
562    /// A Files window's folder or view changed.
563    fn on_files(&self, _room: &MachineRoom, _window: u64, _files: &FilesState) {}
564    fn on_status(&self, _room: &MachineRoom) {}
565    /// Private turned on or off, paused while it reconnects (`private_reason` says why), or came back.
566    fn on_private(&self, _room: &MachineRoom) {}
567    /// An agent holding the machine took a step.
568    fn on_agent_step(&self, _room: &MachineRoom, _step: &AgentStep) {}
569    /// A picture of part of an X11 app window arrived.
570    fn on_app_frame(&self, _room: &MachineRoom, _frame: &AppFrame) {}
571}
572
573impl MachineRoomHooks for () {}
574
575/// One tool call of an agent working the machine, as it finished: the tool, with what, and what
576/// came back. Each turn ends with a step of its own after its calls: its program (`run_code`),
577/// or no tool. Args and result are capped at about 2 KB; larger args arrive as `{ truncated }`.
578#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
579#[serde(rename_all = "camelCase")]
580pub struct AgentStep {
581    /// The agent's id, as in the room's control state.
582    pub agent: String,
583    /// The turn, counting from 1.
584    pub step: u64,
585    /// The call's place in its turn, from 0.
586    pub call: u64,
587    pub tool: String,
588    #[serde(default)]
589    pub args: Map<String, Value>,
590    /// What it returned, as JSON text.
591    #[serde(default)]
592    pub result: String,
593    /// Why it failed.
594    #[serde(default, skip_serializing_if = "Option::is_none")]
595    pub error: Option<String>,
596    /// The turn's model time and usage ride on its own step, so totals add up.
597    #[serde(default)]
598    pub model_ms: f64,
599    #[serde(default)]
600    pub tool_ms: f64,
601    #[serde(default)]
602    pub usage: Usage,
603}
604
605/// A caption of a machine agent's recording, on the video's timeline, after its title card.
606#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
607#[serde(rename_all = "camelCase")]
608pub struct Caption {
609    pub start_ms: f64,
610    pub end_ms: f64,
611    pub text: String,
612}
613
614impl Caption {
615    pub fn from_json(json: &Value) -> Caption {
616        let ms = |key: &str| present(json.get(key)).map_or(0.0, |ms| js_number(Some(ms)));
617        Caption {
618            start_ms: ms("startMs"),
619            end_ms: ms("endMs"),
620            text: js_string(json.get("text"), ""),
621        }
622    }
623}
624
625/// `'video' | 'photo'` in the TypeScript SDK.
626#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
627#[serde(rename_all = "lowercase")]
628pub enum MediaKind {
629    Video,
630    Photo,
631}
632
633/// A recording or photo a machine agent saved with the repository, at `path` under its owner's
634/// root. A video says how long it runs and what its captions say when, which players list as
635/// chapters, and the frames a second the screen sent it (a frame comes when the page paints, so
636/// a still page sends few). A chat's copy carries it on its FILE part, as `media`.
637#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
638#[serde(rename_all = "camelCase")]
639pub struct Media {
640    pub kind: MediaKind,
641    pub title: String,
642    pub path: String,
643    #[serde(default, skip_serializing_if = "Option::is_none")]
644    pub duration_ms: Option<f64>,
645    #[serde(default, skip_serializing_if = "Option::is_none")]
646    pub captions: Option<Vec<Caption>>,
647    #[serde(default, skip_serializing_if = "Option::is_none")]
648    pub frame_rate: Option<f64>,
649}
650
651impl Media {
652    pub fn from_json(json: &Value) -> Media {
653        Media {
654            kind: if json["kind"] == "video" {
655                MediaKind::Video
656            } else {
657                MediaKind::Photo
658            },
659            title: js_string(json.get("title"), ""),
660            path: js_string(json.get("path"), ""),
661            duration_ms: present(json.get("durationMs")).map(|ms| js_number(Some(ms))),
662            captions: json["captions"]
663                .as_array()
664                .map(|captions| captions.iter().map(Caption::from_json).collect()),
665            frame_rate: present(json.get("frameRate")).map(|rate| js_number(Some(rate))),
666        }
667    }
668}
669
670const INPUT_MS: u64 = 30_000;
671const CONTROL_MS: u64 = 30_000;
672const CALL_MS: u64 = 60_000;
673const EXEC_MS: u64 = 120_000;
674const STOP_MS: u64 = 10 * 60_000;
675
676/// Runs one machine tool and returns what the machine reports.
677pub type MachineToolInvoker =
678    Arc<dyn Fn(MachineTool) -> BoxFuture<'static, Result<String>> + Send + Sync>;
679
680/// Runs a shell command, with an optional timeout in milliseconds, and returns its exit code and
681/// output: `{ code, stdout, stderr }`.
682pub type ExecInvoker = Arc<
683    dyn Fn(String, Option<f64>) -> BoxFuture<'static, Result<Map<String, Value>>> + Send + Sync,
684>;
685
686/// What a machine tool reports: `{ text }`, the machine's own words about what it did or found.
687fn says(text: &str) -> Value {
688    json!({
689        "type": "OBJECT",
690        "properties": { "text": { "type": "STRING", "description": text } },
691        "required": ["text"],
692    })
693}
694
695fn text(text: String) -> Map<String, Value> {
696    Map::from_iter([("text".to_string(), Value::String(text))])
697}
698
699fn optional_text(p: &Value, key: &str) -> Option<String> {
700    present(p.get(key)).map(|value| js_string(Some(value), ""))
701}
702
703fn optional_number(p: &Value, key: &str) -> Option<f64> {
704    present(p.get(key)).map(|value| js_number(Some(value)))
705}
706
707/// Every machine tool for a model: pointer and keyboard input, windows, pages, files, processes,
708/// the internet switch, wait, and exec. `invoke` runs a tool and resolves with what the machine
709/// reports; `exec` runs a shell command and resolves with its exit code and output.
710pub fn parrot_tools(invoke: MachineToolInvoker, exec: ExecInvoker) -> Vec<Tool> {
711    let mut tools = Vec::new();
712    let mut add = |name: &str,
713                   description: &str,
714                   properties: Value,
715                   required: &[&str],
716                   reports: &str,
717                   build: fn(&Value) -> MachineTool| {
718        let mut parameters = json!({ "type": "OBJECT", "properties": properties });
719        if !required.is_empty() {
720            parameters["required"] = json!(required);
721        }
722        let invoke = invoke.clone();
723        tools.push(tool(
724            name,
725            description,
726            parameters,
727            says(reports),
728            move |params: Value, _progress| {
729                let params = if params.is_null() { json!({}) } else { params };
730                let run = invoke(build(&params));
731                Box::pin(async move { Ok(text(run.await?)) })
732            },
733        ));
734    };
735
736    add(
737        "move",
738        "Move the pointer to desktop coordinates. Does not click.",
739        json!({
740            "x": { "type": "NUMBER", "description": "X pixel" },
741            "y": { "type": "NUMBER", "description": "Y pixel" },
742        }),
743        &["x", "y"],
744        "Where the pointer went",
745        |p| MachineTool::Move {
746            x: js_number(p.get("x")),
747            y: js_number(p.get("y")),
748        },
749    );
750    add(
751        "click",
752        "Click. Optional coordinates move there first. downMs is how long the button stays down. button right opens context menus; count 2 double clicks.",
753        json!({
754            "x": { "type": "NUMBER", "description": "X pixel" },
755            "y": { "type": "NUMBER", "description": "Y pixel" },
756            "downMs": { "type": "NUMBER", "description": "Hold duration in ms" },
757            "button": { "type": "STRING", "enum": ["left", "right", "middle"], "description": "Mouse button, default left" },
758            "count": { "type": "NUMBER", "description": "Clicks in a row: 2 double clicks, 3 triple clicks. Default 1" },
759        }),
760        &[],
761        "What the click landed on, or that nothing on the screen changed",
762        |p| MachineTool::Click {
763            x: optional_number(p, "x"),
764            y: optional_number(p, "y"),
765            down_ms: optional_number(p, "downMs"),
766            button: match p.get("button").and_then(Value::as_str) {
767                Some("right") => Some(MouseButton::Right),
768                Some("middle") => Some(MouseButton::Middle),
769                _ => None,
770            },
771            count: optional_number(p, "count"),
772        },
773    );
774    add(
775        "drag",
776        "Drag from an optional start point to a destination.",
777        json!({
778            "to": { "type": "OBJECT", "description": "Destination {x,y}" },
779            "from": { "type": "OBJECT", "description": "Start {x,y}" },
780            "downMs": { "type": "NUMBER", "description": "Hold at the end in ms" },
781        }),
782        &["to"],
783        "What the drag did",
784        |p| MachineTool::Drag {
785            to: Point {
786                x: js_number(p.get("to").and_then(|to| to.get("x"))),
787                y: js_number(p.get("to").and_then(|to| to.get("y"))),
788            },
789            from: p.get("from").filter(|from| truthy(from)).map(|from| Point {
790                x: js_number(from.get("x")),
791                y: js_number(from.get("y")),
792            }),
793            down_ms: optional_number(p, "downMs"),
794        },
795    );
796    add(
797        "scroll",
798        "Scroll with the wheel at the current pointer.",
799        json!({
800            "deltaX": { "type": "NUMBER", "description": "Horizontal wheel delta" },
801            "deltaY": { "type": "NUMBER", "description": "Vertical wheel delta" },
802        }),
803        &[],
804        "Whether anything moved, and what is under the pointer when nothing did",
805        |p| MachineTool::Scroll {
806            delta_x: optional_number(p, "deltaX"),
807            delta_y: optional_number(p, "deltaY"),
808        },
809    );
810    add(
811        "type",
812        "Type text at the current focus.",
813        json!({
814            "text": { "type": "STRING", "description": "Text to type" },
815        }),
816        &["text"],
817        "Whether the text went in, and which window took it",
818        |p| MachineTool::Type {
819            text: js_string(p.get("text"), ""),
820        },
821    );
822
823    add(
824        "windows",
825        "List every open desktop window with its id, kind, app, title, position, size, and focus.",
826        json!({}),
827        &[],
828        "Every open window, one per line: id, kind, app, title, position, size and focus",
829        |_| MachineTool::Windows,
830    );
831    add(
832        "focus",
833        "Bring a window to the front and give it keyboard focus.",
834        json!({
835            "window": { "type": "NUMBER", "description": "Window id" },
836        }),
837        &["window"],
838        "Which window has focus now",
839        |p| MachineTool::Focus {
840            window: js_number(p.get("window")),
841        },
842    );
843    add(
844        "place",
845        "Move a window so its top left corner is at desktop coordinates.",
846        json!({
847            "window": { "type": "NUMBER", "description": "Window id" },
848            "x": { "type": "NUMBER", "description": "Desktop X pixel" },
849            "y": { "type": "NUMBER", "description": "Desktop Y pixel" },
850        }),
851        &["window", "x", "y"],
852        "Where the window is now",
853        |p| MachineTool::Place {
854            window: js_number(p.get("window")),
855            x: js_number(p.get("x")),
856            y: js_number(p.get("y")),
857        },
858    );
859    add(
860        "resize",
861        "Resize a window. Apps redraw at the new size.",
862        json!({
863            "window": { "type": "NUMBER", "description": "Window id" },
864            "width": { "type": "NUMBER", "description": "Width in pixels" },
865            "height": { "type": "NUMBER", "description": "Height in pixels" },
866        }),
867        &["window", "width", "height"],
868        "The window's new size",
869        |p| MachineTool::Resize {
870            window: js_number(p.get("window")),
871            width: js_number(p.get("width")),
872            height: js_number(p.get("height")),
873        },
874    );
875    add(
876        "close",
877        "Close a window.",
878        json!({
879            "window": { "type": "NUMBER", "description": "Window id" },
880        }),
881        &["window"],
882        "That the window closed",
883        |p| MachineTool::Close {
884            window: js_number(p.get("window")),
885        },
886    );
887    add(
888        "reload",
889        "Reload a Web window after its page's files change, so it shows them. Previews follow their file on their own, and reload too.",
890        json!({
891            "window": { "type": "NUMBER", "description": "Window id" },
892        }),
893        &["window"],
894        "That the window reloaded",
895        |p| MachineTool::Reload {
896            window: js_number(p.get("window")),
897        },
898    );
899    add(
900        "open",
901        "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 opens a file, text and code in an editor (save with ctrl s) and images, PDFs, video and audio in a preview; 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. Editors and previews follow their file as it changes.",
902        json!({
903            "app": { "type": "STRING", "enum": ["web", "files", "file", "terminal"], "description": "web, files, file or terminal" },
904            "url": { "type": "STRING", "description": "http or https address for a web window" },
905            "path": { "type": "STRING", "description": "Folder for files, or the file to open, relative to /repository" },
906            "command": { "type": "STRING", "description": "Command for a terminal to run in view" },
907        }),
908        &["app"],
909        "The window that opened",
910        |p| MachineTool::Open {
911            app: match p.get("app").and_then(Value::as_str) {
912                Some("files") => WindowApp::Files,
913                Some("file") => WindowApp::File,
914                Some("terminal") => WindowApp::Terminal,
915                _ => WindowApp::Web,
916            },
917            url: optional_text(p, "url"),
918            path: optional_text(p, "path"),
919            command: optional_text(p, "command"),
920        },
921    );
922    add(
923        "key",
924        "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.",
925        json!({
926            "keys": { "type": "ARRAY", "items": { "type": "STRING" }, "description": "Keys held together, e.g. [\"ctrl\", \"s\"]" },
927            "window": { "type": "NUMBER", "description": "Window id to focus first" },
928        }),
929        &["keys"],
930        "Which window took the keys",
931        |p| MachineTool::Key {
932            keys: p
933                .get("keys")
934                .and_then(Value::as_array)
935                .map(|keys| keys.iter().map(|key| js_string(Some(key), "")).collect())
936                .unwrap_or_default(),
937            window: optional_number(p, "window"),
938        },
939    );
940    add(
941        "pageHtml",
942        "Read the page in a Web window: its address and its HTML, trimmed to the body without styles, scripts and SVG. Reads the focused Web window unless window is given.",
943        json!({
944            "window": { "type": "NUMBER", "description": "Web window id" },
945        }),
946        &[],
947        "The page's address and its trimmed HTML",
948        |p| MachineTool::PageHtml {
949            window: optional_number(p, "window"),
950        },
951    );
952    add(
953        "pageScript",
954        "Run JavaScript in the page of a Web window and get its result: a string as it is, anything else as JSON. Runs in the focused Web window unless window is given.",
955        json!({
956            "script": { "type": "STRING", "description": "JavaScript to run in the page" },
957            "window": { "type": "NUMBER", "description": "Web window id" },
958        }),
959        &["script"],
960        "The script's result: a string as it is, anything else as JSON",
961        |p| MachineTool::PageScript {
962            script: js_string(p.get("script"), ""),
963            window: optional_number(p, "window"),
964        },
965    );
966
967    add(
968        "list",
969        "List files under a folder of /repository. Folders end in a slash. With pattern (like **/*.ts) it matches recursively.",
970        json!({
971            "path": { "type": "STRING", "description": "Folder relative to /repository. Defaults to the root." },
972            "pattern": { "type": "STRING", "description": "Glob to match recursively" },
973        }),
974        &[],
975        "The files, one per line, folders ending in a slash",
976        |p| MachineTool::List {
977            path: optional_text(p, "path"),
978            pattern: optional_text(p, "pattern"),
979        },
980    );
981    add(
982        "grep",
983        "Search file contents in /repository with ripgrep. Output is matching files by default, or lines with context, or counts.",
984        json!({
985            "pattern": { "type": "STRING", "description": "Regular expression" },
986            "path": { "type": "STRING", "description": "Folder or file to search" },
987            "glob": { "type": "STRING", "description": "Only files matching this glob" },
988            "ignoreCase": { "type": "BOOLEAN", "description": "Case insensitive" },
989            "context": { "type": "NUMBER", "description": "Lines of context around each match" },
990            "output": { "type": "STRING", "enum": ["files", "lines", "count"], "description": "files, lines, or count" },
991            "max": { "type": "NUMBER", "description": "Result cap, default 50" },
992        }),
993        &["pattern"],
994        "The matching files, lines with context, or counts",
995        |p| MachineTool::Grep {
996            pattern: js_string(p.get("pattern"), ""),
997            path: optional_text(p, "path"),
998            glob: optional_text(p, "glob"),
999            ignore_case: present(p.get("ignoreCase")).map(truthy),
1000            context: optional_number(p, "context"),
1001            output: present(p.get("output"))
1002                .and_then(|output| serde_json::from_value(output.clone()).ok()),
1003            max: optional_number(p, "max"),
1004        },
1005    );
1006    add(
1007        "read",
1008        "Read numbered lines of a file: from line minus before to line plus after. Defaults to the first 100 lines.",
1009        json!({
1010            "path": { "type": "STRING", "description": "File relative to /repository" },
1011            "line": { "type": "NUMBER", "description": "Line to center on, default 1" },
1012            "before": { "type": "NUMBER", "description": "Lines before, default 0" },
1013            "after": { "type": "NUMBER", "description": "Lines after, default 100" },
1014        }),
1015        &["path"],
1016        "The file's numbered lines",
1017        |p| MachineTool::Read {
1018            path: js_string(p.get("path"), ""),
1019            line: optional_number(p, "line"),
1020            before: optional_number(p, "before"),
1021            after: optional_number(p, "after"),
1022        },
1023    );
1024    add(
1025        "write",
1026        "Create or overwrite a file, creating missing folders. With line, insert text after that line instead (0 inserts at the top); read the file first.",
1027        json!({
1028            "path": { "type": "STRING", "description": "File relative to /repository" },
1029            "text": { "type": "STRING", "description": "Full file contents, or with line, the lines to insert" },
1030            "line": { "type": "NUMBER", "description": "Line to insert after, leaving the rest of the file as it is" },
1031        }),
1032        &["path", "text"],
1033        "That the file was written, or what was inserted with the lines around it",
1034        |p| MachineTool::Write {
1035            path: js_string(p.get("path"), ""),
1036            text: js_string(p.get("text"), ""),
1037            line: optional_number(p, "line"),
1038        },
1039    );
1040    add(
1041        "replace",
1042        "Replace an exact string in a file. old must match exactly once unless all is true. Prefer this for edits.",
1043        json!({
1044            "path": { "type": "STRING", "description": "File relative to /repository" },
1045            "old": { "type": "STRING", "description": "Exact text to find" },
1046            "new": { "type": "STRING", "description": "Replacement text" },
1047            "all": { "type": "BOOLEAN", "description": "Replace every match" },
1048        }),
1049        &["path", "old", "new"],
1050        "What changed, with the lines around it",
1051        |p| MachineTool::Replace {
1052            path: js_string(p.get("path"), ""),
1053            old: js_string(p.get("old"), ""),
1054            new: js_string(p.get("new"), ""),
1055            all: present(p.get("all")).map(truthy),
1056        },
1057    );
1058    add(
1059        "remove",
1060        "Delete lines start through end, inclusive. Read the file first.",
1061        json!({
1062            "path": { "type": "STRING", "description": "File relative to /repository" },
1063            "start": { "type": "NUMBER", "description": "First line" },
1064            "end": { "type": "NUMBER", "description": "Last line" },
1065        }),
1066        &["path", "start", "end"],
1067        "What was removed, with the lines around it",
1068        |p| MachineTool::Remove {
1069            path: js_string(p.get("path"), ""),
1070            start: js_number(p.get("start")),
1071            end: js_number(p.get("end")),
1072        },
1073    );
1074
1075    add(
1076        "processes",
1077        "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.",
1078        json!({
1079            "sort": { "type": "STRING", "enum": ["cpu", "memory"], "description": "cpu or memory, default cpu" },
1080            "limit": { "type": "NUMBER", "description": "How many to list, default 25" },
1081            "filter": { "type": "STRING", "description": "Only commands containing this text" },
1082        }),
1083        &[],
1084        "The busiest processes and the machine's load, memory and free disk",
1085        |p| MachineTool::Processes {
1086            sort: match p.get("sort").and_then(Value::as_str) {
1087                Some("memory") => Some(ProcessSort::Memory),
1088                Some("cpu") => Some(ProcessSort::Cpu),
1089                _ => None,
1090            },
1091            limit: optional_number(p, "limit"),
1092            filter: optional_text(p, "filter"),
1093        },
1094    );
1095    add(
1096        "kill",
1097        "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.",
1098        json!({
1099            "pid": { "type": "NUMBER", "description": "Process id from processes" },
1100            "signal": { "type": "STRING", "enum": ["TERM", "KILL"], "description": "TERM (default) or KILL" },
1101        }),
1102        &["pid"],
1103        "Whether the process stopped",
1104        |p| MachineTool::Kill {
1105            pid: js_number(p.get("pid")),
1106            signal: match p.get("signal").and_then(Value::as_str) {
1107                Some("KILL") => Some(ProcessSignal::Kill),
1108                Some("TERM") => Some(ProcessSignal::Term),
1109                _ => None,
1110            },
1111        },
1112    );
1113
1114    add(
1115        "internet",
1116        "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.",
1117        json!({
1118            "mode": { "type": "STRING", "enum": ["private", "public"], "description": "private or public" },
1119        }),
1120        &["mode"],
1121        "How the machine reaches the internet now",
1122        |p| MachineTool::Internet {
1123            mode: if p.get("mode").and_then(Value::as_str) == Some("public") {
1124                InternetMode::Public
1125            } else {
1126                InternetMode::Private
1127            },
1128        },
1129    );
1130    tools.push(tool(
1131        "wait",
1132        &format!("Wait, then look at the screen again: for a page to load, an app to start, or a build running in a terminal to finish. Nothing watches the screen meanwhile, so wait about as long as it should take and wait again if it isn't done. At most {WAIT_MAX_SECONDS} seconds a call. To wait for a command, run it with exec instead, which returns when it ends."),
1133        json!({
1134            "type": "OBJECT",
1135            "properties": {
1136                "seconds": { "type": "NUMBER", "description": format!("Seconds to wait, at most {WAIT_MAX_SECONDS}") },
1137            },
1138            "required": ["seconds"],
1139        }),
1140        says("How long it waited"),
1141        {
1142            let invoke = invoke.clone();
1143            move |params: Value, _progress| {
1144                let run = invoke(MachineTool::Wait {
1145                    seconds: js_number(params.get("seconds")),
1146                });
1147                Box::pin(async move { Ok(text(run.await?)) })
1148            }
1149        },
1150    ));
1151
1152    tools.push(tool(
1153        "exec",
1154        "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.",
1155        json!({
1156            "type": "OBJECT",
1157            "properties": {
1158                "command": { "type": "STRING", "description": "Bash command" },
1159                "timeoutMs": { "type": "NUMBER", "description": "Timeout in ms, default 120000; pass more for installs and builds" },
1160            },
1161            "required": ["command"],
1162        }),
1163        json!({
1164            "type": "OBJECT",
1165            "properties": {
1166                "code": { "type": "INTEGER", "description": "Exit code" },
1167                "stdout": { "type": "STRING", "description": "Standard output" },
1168                "stderr": { "type": "STRING", "description": "Standard error" },
1169            },
1170            "required": ["code", "stdout", "stderr"],
1171        }),
1172        move |params: Value, _progress| {
1173            exec(
1174                js_string(params.get("command"), ""),
1175                optional_number(&params, "timeoutMs"),
1176            )
1177        },
1178    ));
1179    tools
1180}
1181
1182/// `use_computer`'s result when the person chose not to make a repository for it.
1183pub const COMPUTER_DECLINED: &str =
1184    "They chose not to use a computer for this. Do it without one if you can.";
1185
1186const COMPUTER_JOB: &str = "It's for work that needs a screen: using apps and websites, taking screenshots, recording a video. A subagent does the job on the computer and reports back. It sees nothing of this chat except goal, so goal must carry everything: what to do, where, which files, and what to capture or record (screenshots, or a video of the job). Everything it captures is attached to the chat for people to see, and comes back to you too. Slower and costlier than the other tools; use it only when the screen matters.";
1187
1188/// The `use_computer` tool for a Parrot chat: a subagent does a job on the repository's machine,
1189/// started at `spec` when given, else at the repository's latest revision's spec (or
1190/// `STANDARD_SPEC` for a new one). Without a repository (`None`), the person is asked to make one
1191/// first; that's the shape `UI.Chat` offers as a client tool.
1192pub fn computer_tool(repository: Option<&Repository>) -> Function {
1193    let place = if repository.is_some() {
1194        "Do something on the repository's computer, a Linux machine with a desktop."
1195    } else {
1196        "Do something on a computer, a Linux machine with a desktop. This chat has no computer yet, so the person is asked first to make one; if they don't, do the request without a computer."
1197    };
1198    Function {
1199        name: "use_computer".to_string(),
1200        description: Some(format!("{place} {COMPUTER_JOB}")),
1201        parameters: serde_json::from_value::<Schema>(json!({
1202            "type": "OBJECT",
1203            "properties": {
1204                "goal": { "type": "STRING", "description": "Everything the subagent needs: what to do, where, which files, and what to capture or record" },
1205                "spec": {
1206                    "type": "OBJECT",
1207                    "description": "The machine to run on, only when the job needs more than the last one, like a GPU or more memory",
1208                    "properties": {
1209                        "vcpus": { "type": "NUMBER", "description": "vCPUs" },
1210                        "memoryBytes": { "type": "NUMBER", "description": "Memory in bytes" },
1211                        "storageBytes": { "type": "NUMBER", "description": "Disk in bytes" },
1212                        "tflops": { "type": "NUMBER", "description": "GPU TFLOPS (dense BF16), 0 for no GPU" },
1213                        "gpuMemoryBytes": { "type": "NUMBER", "description": "GPU memory in bytes, 0 for no GPU" },
1214                    },
1215                    "required": ["vcpus", "memoryBytes", "storageBytes", "tflops", "gpuMemoryBytes"],
1216                },
1217            },
1218            "required": ["goal"],
1219        }))
1220        .expect("tool schemas are valid"),
1221        returns: serde_json::from_value::<ObjectSchema>(says(
1222            "What the subagent did and found, or that the person chose not to use a computer",
1223        ))
1224        .expect("tool returns are valid"),
1225        default: None,
1226        example: None,
1227        behavior: None,
1228    }
1229}
1230
1231/// One pool of machines and the nodes they share, in dollars.
1232#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
1233#[serde(rename_all = "camelCase")]
1234pub struct PoolPricing {
1235    pub name: String,
1236    /// The Google machine type of its nodes, like n2-standard-8.
1237    pub node_type: String,
1238    /// What one node costs an hour, which a machine alone in the pool pays whole.
1239    pub node_per_hour: f64,
1240    /// What one node sells to machines.
1241    pub node_vcpus: u32,
1242    pub node_memory_bytes: u64,
1243    /// The machines running in it now, and the nodes they fill.
1244    pub machines: u32,
1245    pub nodes: u32,
1246}
1247
1248/// What a machine of a spec pays an hour, in dollars, in the pool it fits.
1249#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
1250#[serde(rename_all = "camelCase")]
1251pub struct Quote {
1252    pub pool: String,
1253    /// As the only machine in its pool, paying for every node it fills.
1254    pub alone: f64,
1255    /// If it started now, sharing its pool's nodes with the machines running there.
1256    pub now: f64,
1257}
1258
1259/// What Termite charges, in dollars. Machines share what their pool's nodes cost by how much
1260/// of a node each takes, so a machine's price moves as others start and stop.
1261#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
1262#[serde(rename_all = "camelCase")]
1263pub struct Pricing {
1264    pub pools: Vec<PoolPricing>,
1265    /// A repository's stored files, per GB a month.
1266    pub storage_per_gb_month: f64,
1267    /// What a private machine sends through the residential proxy, per GB.
1268    pub private_per_gb: f64,
1269    /// What a machine sends to the internet, per GB.
1270    pub internet_per_gb: f64,
1271    /// What the spec asked about pays an hour, or none when none was asked.
1272    pub quote: Option<Quote>,
1273}
1274
1275/// Termite's current prices, and with `spec`, what a machine of it pays an hour. Anyone can
1276/// read them, signed in or not.
1277pub async fn pricing(spec: Option<&Spec>) -> Result<Pricing> {
1278    let mut request = crate::http::client().get(format!("{}/termite/pricing", super::get_url()));
1279    if let Some(spec) = spec {
1280        request = request.query(&[
1281            ("vcpus", spec.vcpus.to_string()),
1282            ("memoryBytes", spec.memory_bytes.to_string()),
1283            ("storageBytes", spec.storage_bytes.to_string()),
1284            ("tflops", spec.tflops.to_string()),
1285            ("gpuMemoryBytes", spec.gpu_memory_bytes.to_string()),
1286        ]);
1287    }
1288    let response = request.send().await?;
1289    Ok(crate::http::ok(response).await?.json().await?)
1290}
1291
1292/// `'called' | 'crashed' | 'skipped'` in the TypeScript SDK.
1293#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
1294#[serde(rename_all = "lowercase")]
1295pub enum WakeReason {
1296    Called,
1297    Crashed,
1298    Skipped,
1299}
1300
1301/// One time a repository woke its machine agent: its code ran wake.sh (`called`),
1302/// entry.sh crashed (`crashed`), or the hourly limit left it out (`skipped`).
1303#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
1304pub struct Wake {
1305    pub id: String,
1306    pub reason: WakeReason,
1307    /// What the agent was told: wake.sh's prompt, or how entry.sh ended.
1308    pub prompt: String,
1309    pub started: DateTime<Utc>,
1310    /// When the woken run ended, or None while it works.
1311    pub finished: Option<DateTime<Utc>>,
1312    pub ok: bool,
1313    /// What the agent said when it finished, or why it stopped.
1314    pub answer: String,
1315}
1316
1317impl Wake {
1318    pub fn from_json(json: &Value) -> Wake {
1319        Wake {
1320            id: js_string(json.get("id"), "undefined"),
1321            reason: match json["reason"].as_str() {
1322                Some("crashed") => WakeReason::Crashed,
1323                Some("skipped") => WakeReason::Skipped,
1324                _ => WakeReason::Called,
1325            },
1326            prompt: js_string(json.get("prompt"), ""),
1327            started: crate::tickets::parse_date(&json["started"]).unwrap_or_default(),
1328            finished: if truthy(&json["finished"]) {
1329                crate::tickets::parse_date(&json["finished"])
1330            } else {
1331                None
1332            },
1333            ok: truthy(&json["ok"]),
1334            answer: js_string(json.get("answer"), ""),
1335        }
1336    }
1337}
1338
1339/// The `opts` argument of the machine calls that take only a group.
1340#[derive(Debug, Clone, Default)]
1341pub struct GroupOptions {
1342    pub group: Option<Group>,
1343}
1344
1345fn authorized(
1346    request: reqwest::RequestBuilder,
1347    authorization: &CredentialsOrApiKey,
1348    group: Option<&Group>,
1349) -> reqwest::RequestBuilder {
1350    let request = request.header(
1351        "Authorization",
1352        match authorization {
1353            CredentialsOrApiKey::Credentials(credentials) => format!("Token {}", credentials.token),
1354            CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
1355        },
1356    );
1357    match group {
1358        Some(group) => request.header("Group", &group.id),
1359        None => request,
1360    }
1361}
1362
1363/// The times a repository woke its agent, newest first.
1364pub async fn wakes(
1365    authorization: &CredentialsOrApiKey,
1366    repository: u64,
1367    query: PageQuery,
1368    opts: GroupOptions,
1369) -> Result<Vec<Wake>> {
1370    let response = authorized(
1371        crate::http::client().get(format!(
1372            "{}/termite/repositories/{repository}/wakes?cursor={}&max={}",
1373            super::get_url(),
1374            query.cursor,
1375            query.max
1376        )),
1377        authorization,
1378        opts.group.as_ref(),
1379    )
1380    .send()
1381    .await?;
1382    let json: Value = crate::http::ok(response).await?.json().await?;
1383    Ok(json
1384        .as_array()
1385        .into_iter()
1386        .flatten()
1387        .map(Wake::from_json)
1388        .collect())
1389}
1390
1391struct Machine {
1392    cursor: HtmlPointer,
1393    controller: Option<String>,
1394    agent: Option<RoomAgent>,
1395    windows: HashMap<u64, Window>,
1396    files: HashMap<u64, FilesState>,
1397    status: MachineStatus,
1398    error: String,
1399    name: String,
1400    private: bool,
1401    private_reason: String,
1402}
1403
1404struct MachineState {
1405    machine: u64,
1406    repository: u64,
1407    spec: Spec,
1408    web: WebRoom,
1409    state: Mutex<Machine>,
1410    hooks: Mutex<Arc<dyn MachineRoomHooks>>,
1411    calls: Mutex<HashMap<String, oneshot::Sender<Result<Value>>>>,
1412}
1413
1414fn lock<T>(mutex: &Mutex<T>) -> MutexGuard<'_, T> {
1415    mutex.lock().unwrap_or_else(PoisonError::into_inner)
1416}
1417
1418/// `{ code, stdout, stderr }` in the TypeScript SDK: how a command ended.
1419#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
1420pub struct ExecResult {
1421    pub code: i64,
1422    pub stdout: String,
1423    pub stderr: String,
1424}
1425
1426/// The `opts` argument of `exec`.
1427#[derive(Debug, Clone, Copy, Default)]
1428pub struct ExecOptions {
1429    pub timeout_ms: Option<u64>,
1430}
1431
1432/// The `opts` argument of `MachineRoom::start`.
1433pub struct StartOptions {
1434    pub spec: Spec,
1435    pub group: Option<Group>,
1436    pub hooks: Option<Arc<dyn MachineRoomHooks>>,
1437    pub private: Option<bool>,
1438}
1439
1440/// The `opts` argument of `MachineRoom::connect` and `MachineRoom::join`
1441/// (which takes no group).
1442#[derive(Default)]
1443pub struct MachineOptions {
1444    pub group: Option<Group>,
1445    pub hooks: Option<Arc<dyn MachineRoomHooks>>,
1446}
1447
1448/// `{ id } | { reference }` in the TypeScript SDK: a machine by id, or by its
1449/// `termite:machine:{id}` reference.
1450#[derive(Debug, Clone, PartialEq, Eq)]
1451pub enum MachineTarget {
1452    Id { id: u64 },
1453    Reference { reference: String },
1454}
1455
1456/// `{ on, reason }` in the TypeScript SDK.
1457#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
1458pub struct PrivateState {
1459    pub on: bool,
1460    pub reason: String,
1461}
1462
1463#[derive(Clone)]
1464pub struct MachineRoom {
1465    room: Room,
1466    inner: Arc<MachineState>,
1467}
1468
1469impl Deref for MachineRoom {
1470    type Target = Room;
1471    fn deref(&self) -> &Room {
1472        &self.room
1473    }
1474}
1475
1476impl MachineRoom {
1477    fn create(room: &Room, hooks: Arc<dyn MachineRoomHooks>, state: &Value) -> MachineRoom {
1478        MachineRoom {
1479            room: room.clone(),
1480            inner: Arc::new(MachineState {
1481                machine: js_number(Some(&state["machine"]["id"])) as u64,
1482                repository: js_number(Some(&state["machine"]["repository"])) as u64,
1483                spec: Spec::from_json(&state["machine"]["spec"]),
1484                web: WebRoom::from_parent(room, hooks.web(), state),
1485                state: Mutex::new(Machine {
1486                    cursor: HtmlPointer::default(),
1487                    controller: None,
1488                    agent: None,
1489                    windows: HashMap::new(),
1490                    files: HashMap::new(),
1491                    status: MachineStatus::Booting,
1492                    error: String::new(),
1493                    name: String::new(),
1494                    private: false,
1495                    private_reason: String::new(),
1496                }),
1497                hooks: Mutex::new(hooks),
1498                calls: Mutex::new(HashMap::new()),
1499            }),
1500        }
1501    }
1502
1503    fn machine_state(&self) -> MutexGuard<'_, Machine> {
1504        lock(&self.inner.state)
1505    }
1506
1507    fn hooks(&self) -> Arc<dyn MachineRoomHooks> {
1508        lock(&self.inner.hooks).clone()
1509    }
1510
1511    /// The machine id, the number `connect` takes.
1512    pub fn machine(&self) -> u64 {
1513        self.inner.machine
1514    }
1515
1516    pub fn repository(&self) -> u64 {
1517        self.inner.repository
1518    }
1519
1520    /// What the machine was granted: its vCPUs, memory, disk and GPU.
1521    pub fn spec(&self) -> Spec {
1522        self.inner.spec
1523    }
1524
1525    /// The desktop page's HTML stream, on the same socket.
1526    pub fn web(&self) -> &WebRoom {
1527        &self.inner.web
1528    }
1529
1530    pub fn cursor(&self) -> HtmlPointer {
1531        self.machine_state().cursor.clone()
1532    }
1533
1534    /// The seat (presence id) whose actions run.
1535    pub fn controller(&self) -> Option<String> {
1536        self.machine_state().controller.clone()
1537    }
1538
1539    /// Set while an agent holds the machine.
1540    pub fn agent(&self) -> Option<RoomAgent> {
1541        self.machine_state().agent.clone()
1542    }
1543
1544    pub fn windows(&self) -> HashMap<u64, Window> {
1545        self.machine_state().windows.clone()
1546    }
1547
1548    /// Each Files window's folder and view, by window id.
1549    pub fn files(&self) -> HashMap<u64, FilesState> {
1550        self.machine_state().files.clone()
1551    }
1552
1553    pub fn status(&self) -> MachineStatus {
1554        self.machine_state().status
1555    }
1556
1557    /// Why the machine failed, when it did.
1558    pub fn error(&self) -> String {
1559        self.machine_state().error.clone()
1560    }
1561
1562    /// The repository's name, so a guest who joined by code knows what it is.
1563    pub fn name(&self) -> String {
1564        self.machine_state().name.clone()
1565    }
1566
1567    /// Its connections go out only from a residential address, billed per GB to whoever pays for
1568    /// the machine. Stays true while private is paused.
1569    pub fn private(&self) -> bool {
1570        self.machine_state().private
1571    }
1572
1573    /// Why private is paused while it reconnects, like a payer out of balance. Its internet is cut
1574    /// until then. Empty while private carries traffic, or is off.
1575    pub fn private_reason(&self) -> String {
1576        self.machine_state().private_reason.clone()
1577    }
1578
1579    /// Apply a connection snapshot `{ machine, control, cursor, windows, files, private }`. The
1580    /// desktop's copy follows the connection as a bootstrap of this seat's own.
1581    pub fn hydrate(&self, state: &Value) {
1582        if state["control"].is_object() {
1583            self.apply_control(&state["control"]);
1584        }
1585        let cursor = serde_json::from_value::<HtmlPointer>(state["cursor"].clone()).ok();
1586        {
1587            let mut machine = self.machine_state();
1588            if let Ok(status) = serde_json::from_value(state["machine"]["status"].clone()) {
1589                machine.status = status;
1590            }
1591            if state["machine"].is_object() {
1592                machine.error = js_string(state["machine"].get("error"), "");
1593                machine.name = js_string(state["machine"].get("name"), "");
1594            }
1595            if let Some(cursor) = &cursor {
1596                machine.cursor = cursor.clone();
1597            }
1598            if let Some(windows) = state["windows"].as_array() {
1599                machine.windows = windows
1600                    .iter()
1601                    .map(Window::from_json)
1602                    .map(|window| (window.id, window))
1603                    .collect();
1604            }
1605            if let Some(files) = state["files"].as_array() {
1606                machine.files = files
1607                    .iter()
1608                    .map(|row| {
1609                        (
1610                            js_number(row.get("window")) as u64,
1611                            FilesState::from_json(row),
1612                        )
1613                    })
1614                    .collect();
1615            }
1616            if truthy(&state["private"]) {
1617                machine.private = truthy(&state["private"]["on"]);
1618                machine.private_reason = js_string(state["private"].get("reason"), "");
1619            }
1620        }
1621        if let Some(cursor) = cursor {
1622            self.hooks().on_cursor(self, &cursor);
1623        }
1624    }
1625
1626    pub fn watch(&self, hooks: Arc<dyn MachineRoomHooks>) {
1627        if let Some(web) = hooks.web() {
1628            self.inner.web.set_hooks(web);
1629        }
1630        *lock(&self.inner.hooks) = hooks;
1631    }
1632
1633    /// Whether your actions run: you control it and no agent holds it.
1634    pub fn controlling(&self, me: &Presence) -> bool {
1635        let machine = self.machine_state();
1636        machine.agent.is_none() && machine.controller == Some(me.id())
1637    }
1638
1639    /// Hand control to a seat, or take it yourself without one. While an agent holds the machine this stops the agent.
1640    pub async fn set_controller(&self, seat: Option<&str>) -> Result<()> {
1641        let data = match seat.filter(|seat| !seat.is_empty()) {
1642            Some(seat) => json!({ "seat": seat }),
1643            None => json!({}),
1644        };
1645        self.request("control-call", data, CONTROL_MS, "Control timed out.")
1646            .await?;
1647        Ok(())
1648    }
1649
1650    /// Presence changed: tell whoever is watching now.
1651    pub fn emit_presence(&self) {
1652        self.hooks().on_presence(self);
1653    }
1654
1655    pub fn emit_closed(&self) {
1656        self.hooks().on_closed(self);
1657    }
1658
1659    fn apply_control(&self, control: &Value) {
1660        let mut machine = self.machine_state();
1661        machine.controller = control["controller"].as_str().map(str::to_string);
1662        machine.agent = if control["agent"].is_object() {
1663            Some(RoomAgent::from_json(&control["agent"]))
1664        } else {
1665            None
1666        };
1667    }
1668
1669    /// Run a tool as this seat. Only the controller's tools run. `wait` pauses here, at most
1670    /// `WAIT_MAX_SECONDS`.
1671    pub async fn invoke_tool(&self, tool: &MachineTool) -> Result<String> {
1672        if let MachineTool::Wait { seconds } = tool {
1673            let seconds = if seconds.is_nan() {
1674                0.0
1675            } else {
1676                seconds.clamp(0.0, WAIT_MAX_SECONDS as f64)
1677            };
1678            tokio::time::sleep(Duration::from_secs_f64(seconds)).await;
1679            return Ok(format!("Waited {seconds} seconds."));
1680        }
1681        let result = if tool.is_input() {
1682            let kind = serde_json::to_value(tool)?["kind"].clone();
1683            self.request(
1684                "machine-tool-call",
1685                json!({ "tool": tool }),
1686                INPUT_MS,
1687                &format!("Tool timed out: {}", js_string(Some(&kind), "")),
1688            )
1689            .await?
1690        } else {
1691            self.call(json!({ "kind": "tool", "tool": tool }), CALL_MS)
1692                .await?
1693        };
1694        Ok(match result {
1695            Value::Null => String::new(),
1696            Value::String(result) => result,
1697            result => result.to_string(),
1698        })
1699    }
1700
1701    /// Run a shell command as `agent` in /repository with DISPLAY=:0, so GUI apps open as desktop windows.
1702    pub async fn exec(&self, command: &str, opts: ExecOptions) -> Result<ExecResult> {
1703        let timeout_ms = opts.timeout_ms.unwrap_or(EXEC_MS);
1704        let result = self
1705            .call(
1706                json!({ "kind": "exec", "command": command, "timeoutMs": timeout_ms }),
1707                timeout_ms + 15_000,
1708            )
1709            .await?;
1710        Ok(ExecResult {
1711            code: match result.get("code") {
1712                None | Some(Value::Null) => -1,
1713                code => js_number(code) as i64,
1714            },
1715            stdout: js_string(result.get("stdout"), ""),
1716            stderr: js_string(result.get("stderr"), ""),
1717        })
1718    }
1719
1720    /// Size the machine's desktop to this seat's screen, clamped to `VIEWPORT`. Only the controller can.
1721    pub async fn set_viewport(&self, width: f64, height: f64) -> Result<()> {
1722        let size = clamp_viewport(Viewport { width, height });
1723        self.call(
1724            json!({ "kind": "viewport", "width": size.width, "height": size.height }),
1725            CALL_MS,
1726        )
1727        .await?;
1728        Ok(())
1729    }
1730
1731    /// Open a file in an app on the machine, for everyone to see: text and code in an editor
1732    /// window, images, PDFs, video and audio in a preview, anything else with an installed
1733    /// opener. Only the controller can.
1734    pub async fn open(&self, path: &str) -> Result<()> {
1735        self.call(json!({ "kind": "open", "path": path }), CALL_MS)
1736            .await?;
1737        Ok(())
1738    }
1739
1740    /// Put a Files window on a folder and view for every seat. Only the controller can.
1741    pub async fn set_files(&self, window: u64, files: &FilesState) -> Result<()> {
1742        self.call(
1743            json!({ "kind": "files", "window": window, "path": files.path, "view": files.view }),
1744            CALL_MS,
1745        )
1746        .await?;
1747        Ok(())
1748    }
1749
1750    /// Save a new revision and shut down. The room closes afterwards.
1751    pub async fn stop(&self) -> Result<()> {
1752        match self.call(json!({ "kind": "stop" }), STOP_MS).await {
1753            Ok(_) => Ok(()),
1754            // The machine announces it closed before it answers the stop itself.
1755            Err(_) if self.status() == MachineStatus::Stopped => Ok(()),
1756            Err(error) => Err(error),
1757        }
1758    }
1759
1760    async fn call(&self, call: Value, timeout_ms: u64) -> Result<Value> {
1761        self.request(
1762            "machine-call",
1763            json!({ "call": call }),
1764            timeout_ms,
1765            "Machine call timed out.",
1766        )
1767        .await
1768    }
1769
1770    /// Posts `event` with a new id; its answer (`control-result`, `machine-tool-result` or
1771    /// `machine-result`) settles it.
1772    async fn request(
1773        &self,
1774        event: &str,
1775        mut data: Value,
1776        timeout_ms: u64,
1777        timed_out: &str,
1778    ) -> Result<Value> {
1779        let id = uuid::Uuid::new_v4().to_string();
1780        let (resolve, result) = oneshot::channel();
1781        lock(&self.inner.calls).insert(id.clone(), resolve);
1782        data["id"] = json!(id);
1783        self.post(&json!({ "event": event, "data": data }));
1784        match tokio::time::timeout(Duration::from_millis(timeout_ms), result).await {
1785            Ok(Ok(result)) => result,
1786            Ok(Err(_)) => Err(Error::Message("Machine closed.".to_string())),
1787            Err(_) => {
1788                lock(&self.inner.calls).remove(&id);
1789                Err(Error::Message(timed_out.to_string()))
1790            }
1791        }
1792    }
1793
1794    fn settle(&self, data: &Value) {
1795        let Some(id) = data["id"].as_str() else {
1796            return;
1797        };
1798        let Some(pending) = lock(&self.inner.calls).remove(id) else {
1799            return;
1800        };
1801        let _ = pending.send(if truthy(&data["error"]) {
1802            Err(Error::Message(js_string(data.get("error"), "")))
1803        } else {
1804            Ok(data["result"].clone())
1805        });
1806    }
1807
1808    pub fn parrot_tools(&self) -> Vec<Tool> {
1809        let invoking = self.clone();
1810        let executing = self.clone();
1811        parrot_tools(
1812            Arc::new(move |tool| {
1813                let room = invoking.clone();
1814                Box::pin(async move { room.invoke_tool(&tool).await })
1815            }),
1816            Arc::new(move |command, timeout_ms| {
1817                let room = executing.clone();
1818                Box::pin(async move {
1819                    let result = room
1820                        .exec(
1821                            &command,
1822                            ExecOptions {
1823                                timeout_ms: timeout_ms.map(|ms| ms as u64),
1824                            },
1825                        )
1826                        .await?;
1827                    Ok(serde_json::from_value(serde_json::to_value(result)?)?)
1828                })
1829            }),
1830        )
1831    }
1832
1833    /// A binary frame: an app frame reaches `on_app_frame`.
1834    pub fn handle_binary(&self, data: &[u8]) -> bool {
1835        let Some(frame) = AppFrame::from_bytes(data) else {
1836            return false;
1837        };
1838        self.hooks().on_app_frame(self, &frame);
1839        true
1840    }
1841
1842    /// Ask for a whole picture of app window `window`, after a frame of it was skipped. Anyone
1843    /// in the room can.
1844    pub fn repaint(&self, window: u32) {
1845        self.post(&json!({ "event": "app-repaint", "data": { "window": window } }));
1846    }
1847
1848    pub fn handle_event(&self, packet: &Value) -> bool {
1849        if self.inner.web.handle_event(packet) {
1850            return true;
1851        }
1852        let data = &packet["data"];
1853        let hooks = self.hooks();
1854        match packet["event"].as_str().unwrap_or_default() {
1855            "room-control" => {
1856                let empty = json!({});
1857                self.apply_control(if data.is_object() { data } else { &empty });
1858                hooks.on_control(self);
1859                true
1860            }
1861            "machine-cursor" => {
1862                if let Ok(cursor) = serde_json::from_value::<HtmlPointer>(data["cursor"].clone()) {
1863                    self.machine_state().cursor = cursor.clone();
1864                    hooks.on_cursor(self, &cursor);
1865                }
1866                true
1867            }
1868            "machine-tool-call" => {
1869                if let Ok(tool) = serde_json::from_value::<MachineTool>(data["tool"].clone()) {
1870                    hooks.on_tool(self, &tool);
1871                }
1872                true
1873            }
1874            "control-result" | "machine-tool-result" | "machine-result" => {
1875                self.settle(data);
1876                true
1877            }
1878            "machine-status" => {
1879                if let Ok(status) = serde_json::from_value(data["status"].clone()) {
1880                    self.machine_state().status = status;
1881                }
1882                hooks.on_status(self);
1883                true
1884            }
1885            "machine-window" => {
1886                if !truthy(&data["window"]) {
1887                    return true;
1888                }
1889                let window = Window::from_json(&data["window"]);
1890                self.machine_state()
1891                    .windows
1892                    .insert(window.id, window.clone());
1893                hooks.on_window(self, &window);
1894                true
1895            }
1896            "machine-window-closed" => {
1897                let id = js_number(data.get("id")) as u64;
1898                {
1899                    let mut machine = self.machine_state();
1900                    machine.windows.remove(&id);
1901                    machine.files.remove(&id);
1902                }
1903                hooks.on_window_closed(self, id);
1904                true
1905            }
1906            "machine-files" => {
1907                let window = js_number(data.get("window")) as u64;
1908                let files = FilesState::from_json(data);
1909                self.machine_state().files.insert(window, files.clone());
1910                hooks.on_files(self, window, &files);
1911                true
1912            }
1913            "machine-private" => {
1914                {
1915                    let mut machine = self.machine_state();
1916                    machine.private = truthy(&data["on"]);
1917                    machine.private_reason = js_string(data.get("reason"), "");
1918                }
1919                hooks.on_private(self);
1920                true
1921            }
1922            "machine-agent-step" => {
1923                if let Ok(step) = serde_json::from_value::<AgentStep>(data.clone()) {
1924                    hooks.on_agent_step(self, &step);
1925                }
1926                true
1927            }
1928            "machine-closed" => {
1929                {
1930                    let mut machine = self.machine_state();
1931                    if let Ok(status) = serde_json::from_value(data["status"].clone()) {
1932                        machine.status = status;
1933                    }
1934                    if let Some(error) = data.get("error") {
1935                        machine.error = js_string(Some(error), "");
1936                    }
1937                }
1938                hooks.on_status(self);
1939                for (_, pending) in lock(&self.inner.calls).drain() {
1940                    let _ = pending.send(Err(Error::Message("Machine closed.".to_string())));
1941                }
1942                hooks.on_closed(self);
1943                true
1944            }
1945            _ => false,
1946        }
1947    }
1948
1949    /// Boot the repository's machine, or return the one already live, and connect to it.
1950    /// `spec` is what it asks for; `room.spec()` is what it was granted, and a live machine
1951    /// keeps its own. `private` sends its connections out from a residential address, billed
1952    /// per GB to whoever pays for the machine; on a live machine it switches it.
1953    pub async fn start(
1954        authorization: &CredentialsOrApiKey,
1955        repository: u64,
1956        opts: StartOptions,
1957    ) -> Result<(MachineRoom, Presence)> {
1958        let mut body = json!({ "spec": opts.spec });
1959        if let Some(private) = opts.private {
1960            body["private"] = json!(private);
1961        }
1962        let response = authorized(
1963            crate::http::client().post(format!(
1964                "{}/termite/repositories/{repository}/machine",
1965                super::get_url()
1966            )),
1967            authorization,
1968            opts.group.as_ref(),
1969        )
1970        .json(&body)
1971        .send()
1972        .await?;
1973        let json: Value = crate::http::ok(response).await?.json().await?;
1974        MachineRoom::connect(
1975            authorization,
1976            &MachineTarget::Id {
1977                id: js_number(json.get("id")) as u64,
1978            },
1979            MachineOptions {
1980                group: opts.group,
1981                hooks: opts.hooks,
1982            },
1983        )
1984        .await
1985    }
1986
1987    /// Save and shut down a repository's machine without joining its room. For its owner or group members.
1988    pub async fn shutdown(
1989        authorization: &CredentialsOrApiKey,
1990        repository: u64,
1991        opts: GroupOptions,
1992    ) -> Result<()> {
1993        let response = authorized(
1994            crate::http::client().post(format!(
1995                "{}/termite/repositories/{repository}/machine/stop",
1996                super::get_url()
1997            )),
1998            authorization,
1999            opts.group.as_ref(),
2000        )
2001        .json(&json!({}))
2002        .send()
2003        .await?;
2004        crate::http::ok(response).await?;
2005        Ok(())
2006    }
2007
2008    /// Turn private on or off for a repository's live machine, for its owner or group members.
2009    /// Resolves to the machine's private state and, while it's paused, why.
2010    pub async fn set_private(
2011        authorization: &CredentialsOrApiKey,
2012        repository: u64,
2013        on: bool,
2014        opts: GroupOptions,
2015    ) -> Result<PrivateState> {
2016        let response = authorized(
2017            crate::http::client().post(format!(
2018                "{}/termite/repositories/{repository}/machine/private",
2019                super::get_url()
2020            )),
2021            authorization,
2022            opts.group.as_ref(),
2023        )
2024        .json(&json!({ "on": on }))
2025        .send()
2026        .await?;
2027        let json: Value = crate::http::ok(response).await?.json().await?;
2028        Ok(PrivateState {
2029            on: truthy(&json["on"]),
2030            reason: js_string(json.get("reason"), ""),
2031        })
2032    }
2033
2034    /// Connect to a live machine by id, or by its `termite:machine:{id}` reference.
2035    pub async fn connect(
2036        authorization: &CredentialsOrApiKey,
2037        target: &MachineTarget,
2038        opts: MachineOptions,
2039    ) -> Result<(MachineRoom, Presence)> {
2040        MachineRoom::open_room(
2041            Authorization::Server {
2042                authorization: authorization.clone(),
2043                server: match target {
2044                    MachineTarget::Id { id } => format!("termite:machine:{id}"),
2045                    MachineTarget::Reference { reference } => reference.clone(),
2046                },
2047                group: opts.group.as_ref().map(|group| group.id.clone()),
2048            },
2049            opts.hooks.unwrap_or_else(|| Arc::new(())),
2050        )
2051        .await
2052    }
2053
2054    /// Join a machine someone shared with an access code.
2055    pub async fn join(
2056        authorization: &CredentialsOrApiKey,
2057        access_code: &str,
2058        opts: MachineOptions,
2059    ) -> Result<(MachineRoom, Presence)> {
2060        MachineRoom::open_room(
2061            Authorization::AccessCode {
2062                authorization: authorization.clone(),
2063                access_code: access_code.to_string(),
2064            },
2065            opts.hooks.unwrap_or_else(|| Arc::new(())),
2066        )
2067        .await
2068    }
2069
2070    async fn open_room(
2071        auth: Authorization,
2072        hooks: Arc<dyn MachineRoomHooks>,
2073    ) -> Result<(MachineRoom, Presence)> {
2074        let machine_hooks = Arc::new(MachineHooks {
2075            room: Mutex::new(None),
2076            hooks,
2077        });
2078        let me = connect_server(
2079            auth,
2080            &format!("{}/termite/machine/live", super::get_url()),
2081            machine_hooks.clone(),
2082        )
2083        .await?;
2084        let room = machine_hooks
2085            .room()
2086            .ok_or_else(|| Error::Message("Room not found".to_string()))?;
2087        room.emit_presence();
2088        Ok((room, me))
2089    }
2090}
2091
2092struct MachineHooks {
2093    room: Mutex<Option<MachineRoom>>,
2094    hooks: Arc<dyn MachineRoomHooks>,
2095}
2096
2097impl MachineHooks {
2098    fn room(&self) -> Option<MachineRoom> {
2099        lock(&self.room).clone()
2100    }
2101}
2102
2103impl Hooks for MachineHooks {
2104    fn create_room(&self, room: &Room, state: &Value) {
2105        *lock(&self.room) = Some(MachineRoom::create(room, self.hooks.clone(), state));
2106    }
2107
2108    fn on_presence(&self, _room: &Room) {
2109        if let Some(room) = self.room() {
2110            room.emit_presence();
2111        }
2112    }
2113
2114    fn on_connection(&self, _room: &Room, state: &Value) {
2115        if let Some(room) = self.room() {
2116            room.hydrate(state);
2117        }
2118    }
2119
2120    fn on_event(&self, _room: &Room, packet: &Value) -> bool {
2121        self.room().is_some_and(|room| room.handle_event(packet))
2122    }
2123
2124    fn on_binary(&self, _room: &Room, data: &[u8]) {
2125        if let Some(room) = self.room() {
2126            room.handle_binary(data);
2127        }
2128    }
2129
2130    fn on_closed(&self, _room: &Room, _reason: Option<&str>) {
2131        if let Some(room) = self.room() {
2132            room.emit_closed();
2133        }
2134    }
2135}
2136
2137#[cfg(test)]
2138mod tests {
2139    use super::*;
2140
2141    #[test]
2142    fn reads_an_app_frames_header_and_its_jpeg() {
2143        let mut data = vec![1u8, 1];
2144        data.extend(0x0040_0007u32.to_be_bytes());
2145        data.extend(9u32.to_be_bytes());
2146        for n in [640u16, 400, 0, 0, 640, 400] {
2147            data.extend(n.to_be_bytes());
2148        }
2149        data.extend([0xff, 0xd8, 0xff]);
2150        let frame = AppFrame::from_bytes(&data).unwrap();
2151        assert_eq!(
2152            frame,
2153            AppFrame {
2154                window: 0x0040_0007,
2155                seq: 9,
2156                key: true,
2157                window_width: 640,
2158                window_height: 400,
2159                x: 0,
2160                y: 0,
2161                width: 640,
2162                height: 400,
2163                jpeg: vec![0xff, 0xd8, 0xff],
2164            }
2165        );
2166        data[1] = 0;
2167        assert!(!AppFrame::from_bytes(&data).unwrap().key);
2168        assert_eq!(AppFrame::from_bytes(&data[..21]), None);
2169        data[0] = 2;
2170        assert_eq!(AppFrame::from_bytes(&data), None);
2171    }
2172
2173    #[test]
2174    fn reads_media_with_its_captions() {
2175        let video = Media::from_json(&json!({
2176            "kind": "video", "title": "Signup", "path": "/termite/repositories/1/media/2.mp4",
2177            "durationMs": 7_200, "captions": [{ "startMs": 1_200, "endMs": 3_000, "text": "Typing" }],
2178            "frameRate": 24.5,
2179        }));
2180        assert_eq!(
2181            video,
2182            Media {
2183                kind: MediaKind::Video,
2184                title: "Signup".into(),
2185                path: "/termite/repositories/1/media/2.mp4".into(),
2186                duration_ms: Some(7_200.0),
2187                captions: Some(vec![Caption {
2188                    start_ms: 1_200.0,
2189                    end_ms: 3_000.0,
2190                    text: "Typing".into(),
2191                }]),
2192                frame_rate: Some(24.5),
2193            }
2194        );
2195        let photo =
2196            Media::from_json(&json!({ "kind": "photo", "title": "Saved", "path": "/p.jpg" }));
2197        assert_eq!(photo.kind, MediaKind::Photo);
2198        assert_eq!(
2199            (photo.duration_ms, photo.captions, photo.frame_rate),
2200            (None, None, None)
2201        );
2202    }
2203}