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