fauna-api 0.0.0-stage → 1.0.676

package/dist/src/termite/os.js

@@ -0,0 +1,572 @@
+/**
+ * A live machine: one running boot of a Repository. It's a PageRoom whose
+ * page is the machine's desktop, one HTML page that is the whole OS, so it
+ * streams like any browser room. Window tools, file tools, exec, and stop ride
+ * the same socket as `machine-call`.
+ */
+import { PageRoom, parrotTools as browserParrotTools } from "../marmot/browser.js";
+import { Presence, connect as connectServer } from "../shared/server.js";
+import { Termite } from "./index.js";
+export const Window = {
+    fromJSON(json) {
+        const kind = json.kind === 'web' || json.kind === 'files' || json.kind === 'preview' ? json.kind : 'app';
+        return {
+            id: Number(json.id),
+            kind,
+            app: String(json.app ?? kind),
+            title: String(json.title ?? ""),
+            x: Number(json.x ?? 0),
+            y: Number(json.y ?? 0),
+            width: Number(json.width ?? 0),
+            height: Number(json.height ?? 0),
+            focused: Boolean(json.focused),
+        };
+    },
+};
+export const FilesState = {
+    fromJSON(json) {
+        return { path: String(json?.path ?? ""), view: json?.view === 'cozy' ? 'cozy' : 'list' };
+    },
+};
+/** The smallest and largest desktop a machine draws. The largest is the guest's X screen. */
+export const VIEWPORT = {
+    min: { width: 640, height: 400 },
+    max: { width: 2560, height: 1600 },
+};
+/** A desktop size inside `VIEWPORT`, in whole pixels. */
+export function clampViewport(size) {
+    return {
+        width: Math.round(Math.min(VIEWPORT.max.width, Math.max(VIEWPORT.min.width, size.width))),
+        height: Math.round(Math.min(VIEWPORT.max.height, Math.max(VIEWPORT.min.height, size.height))),
+    };
+}
+const DESKTOP_TOOLS = ["move", "click", "drag", "scroll", "type"];
+const DESKTOP_KINDS = new Set(DESKTOP_TOOLS);
+const CALL_MS = 60000;
+const EXEC_MS = 120000;
+const STOP_MS = 10 * 60000;
+/**
+ * Every machine tool for a model: desktop input, windows, files, and exec.
+ * `invoke` runs a tool; `exec` runs a shell command and returns its result as text.
+ */
+export function parrotTools(invoke, exec) {
+    const tools = [...browserParrotTools(new Set(DESKTOP_TOOLS), (tool) => invoke(tool))];
+    const add = (name, description, properties, required, build) => {
+        tools.push({
+            function: { name, description, parameters: { type: "OBJECT", properties, ...(required.length ? { required } : {}) } },
+            evaluate: async (params) => invoke(build(params ?? {})),
+        });
+    };
+    const num = (value) => value == null ? undefined : Number(value);
+    add("windows", "List every open desktop window with its id, kind, app, title, position, size, and focus.", {}, [], () => ({ kind: 'windows' }));
+    add("focus", "Bring a window to the front and give it keyboard focus.", {
+        window: { type: "NUMBER", description: "Window id" },
+    }, ["window"], (p) => ({ kind: 'focus', window: Number(p.window) }));
+    add("place", "Move a window so its top left corner is at desktop coordinates.", {
+        window: { type: "NUMBER", description: "Window id" },
+        x: { type: "NUMBER", description: "Desktop X pixel" },
+        y: { type: "NUMBER", description: "Desktop Y pixel" },
+    }, ["window", "x", "y"], (p) => ({ kind: 'place', window: Number(p.window), x: Number(p.x), y: Number(p.y) }));
+    add("resize", "Resize a window. Apps redraw at the new size.", {
+        window: { type: "NUMBER", description: "Window id" },
+        width: { type: "NUMBER", description: "Width in pixels" },
+        height: { type: "NUMBER", description: "Height in pixels" },
+    }, ["window", "width", "height"], (p) => ({ kind: 'resize', window: Number(p.window), width: Number(p.width), height: Number(p.height) }));
+    add("close", "Close a window.", {
+        window: { type: "NUMBER", description: "Window id" },
+    }, ["window"], (p) => ({ kind: 'close', window: Number(p.window) }));
+    add("reload", "Reload a Web window after its page's files change, so it shows them. Previews follow their file on their own, and reload too.", {
+        window: { type: "NUMBER", description: "Window id" },
+    }, ["window"], (p) => ({ kind: 'reload', window: Number(p.window) }));
+    add("open", "Open a window on the desktop: web opens a Web window at url (http or https; serve local pages over HTTP first, since file:// pages don't load); files opens a Files window at a folder; file previews a file (images, PDFs, video, audio, text); terminal opens a terminal, running command in view; when it ends the window stays open at a prompt, so people can read the result and you can type more. A preview follows its file as it changes.", {
+        app: { type: "STRING", enum: ["web", "files", "file", "terminal"], description: "web, files, file or terminal" },
+        url: { type: "STRING", description: "http or https address for a web window" },
+        path: { type: "STRING", description: "Folder for files, or the file to preview, relative to /repository" },
+        command: { type: "STRING", description: "Command for a terminal to run in view" },
+    }, ["app"], (p) => ({
+        kind: 'open',
+        app: p.app === 'files' || p.app === 'file' || p.app === 'terminal' ? p.app : 'web',
+        ...(p.url != null ? { url: String(p.url) } : {}),
+        ...(p.path != null ? { path: String(p.path) } : {}),
+        ...(p.command != null ? { command: String(p.command) } : {}),
+    }));
+    add("key", "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.", {
+        keys: { type: "ARRAY", items: { type: "STRING" }, description: "Keys held together, e.g. [\"ctrl\", \"s\"]" },
+        window: { type: "NUMBER", description: "Window id to focus first" },
+    }, ["keys"], (p) => ({ kind: 'key', keys: (Array.isArray(p.keys) ? p.keys : []).map(String), ...(p.window != null ? { window: Number(p.window) } : {}) }));
+    add("list", "List files under a folder of /repository. Folders end in a slash. With pattern (like **/*.ts) it matches recursively.", {
+        path: { type: "STRING", description: "Folder relative to /repository. Defaults to the root." },
+        pattern: { type: "STRING", description: "Glob to match recursively" },
+    }, [], (p) => ({ kind: 'list', ...(p.path != null ? { path: String(p.path) } : {}), ...(p.pattern != null ? { pattern: String(p.pattern) } : {}) }));
+    add("grep", "Search file contents in /repository with ripgrep. Output is matching files by default, or lines with context, or counts.", {
+        pattern: { type: "STRING", description: "Regular expression" },
+        path: { type: "STRING", description: "Folder or file to search" },
+        glob: { type: "STRING", description: "Only files matching this glob" },
+        ignoreCase: { type: "BOOLEAN", description: "Case insensitive" },
+        context: { type: "NUMBER", description: "Lines of context around each match" },
+        output: { type: "STRING", enum: ["files", "lines", "count"], description: "files, lines, or count" },
+        max: { type: "NUMBER", description: "Result cap, default 50" },
+    }, ["pattern"], (p) => ({
+        kind: 'grep',
+        pattern: String(p.pattern ?? ""),
+        ...(p.path != null ? { path: String(p.path) } : {}),
+        ...(p.glob != null ? { glob: String(p.glob) } : {}),
+        ...(p.ignoreCase != null ? { ignoreCase: Boolean(p.ignoreCase) } : {}),
+        ...(p.context != null ? { context: Number(p.context) } : {}),
+        ...(p.output != null ? { output: p.output } : {}),
+        ...(p.max != null ? { max: Number(p.max) } : {}),
+    }));
+    add("read", "Read numbered lines of a file: from line minus before to line plus after. Defaults to the first 100 lines.", {
+        path: { type: "STRING", description: "File relative to /repository" },
+        line: { type: "NUMBER", description: "Line to center on, default 1" },
+        before: { type: "NUMBER", description: "Lines before, default 0" },
+        after: { type: "NUMBER", description: "Lines after, default 100" },
+    }, ["path"], (p) => ({ kind: 'read', path: String(p.path ?? ""), line: num(p.line), before: num(p.before), after: num(p.after) }));
+    add("write", "Create or overwrite a file, creating missing folders.", {
+        path: { type: "STRING", description: "File relative to /repository" },
+        text: { type: "STRING", description: "Full file contents" },
+    }, ["path", "text"], (p) => ({ kind: 'write', path: String(p.path ?? ""), text: String(p.text ?? "") }));
+    add("replace", "Replace an exact string in a file. old must match exactly once unless all is true. Prefer this for edits.", {
+        path: { type: "STRING", description: "File relative to /repository" },
+        old: { type: "STRING", description: "Exact text to find" },
+        new: { type: "STRING", description: "Replacement text" },
+        all: { type: "BOOLEAN", description: "Replace every match" },
+    }, ["path", "old", "new"], (p) => ({ kind: 'replace', path: String(p.path ?? ""), old: String(p.old ?? ""), new: String(p.new ?? ""), ...(p.all != null ? { all: Boolean(p.all) } : {}) }));
+    add("insert", "Insert text after a line number. 0 inserts at the top. Read the file first.", {
+        path: { type: "STRING", description: "File relative to /repository" },
+        after: { type: "NUMBER", description: "Line to insert after" },
+        text: { type: "STRING", description: "Text to insert" },
+    }, ["path", "after", "text"], (p) => ({ kind: 'insert', path: String(p.path ?? ""), after: Number(p.after), text: String(p.text ?? "") }));
+    add("remove", "Delete lines start through end, inclusive. Read the file first.", {
+        path: { type: "STRING", description: "File relative to /repository" },
+        start: { type: "NUMBER", description: "First line" },
+        end: { type: "NUMBER", description: "Last line" },
+    }, ["path", "start", "end"], (p) => ({ kind: 'remove', path: String(p.path ?? ""), start: Number(p.start), end: Number(p.end) }));
+    add("processes", "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.", {
+        sort: { type: "STRING", enum: ["cpu", "memory"], description: "cpu or memory, default cpu" },
+        limit: { type: "NUMBER", description: "How many to list, default 25" },
+        filter: { type: "STRING", description: "Only commands containing this text" },
+    }, [], (p) => ({
+        kind: 'processes',
+        ...(p.sort === 'memory' || p.sort === 'cpu' ? { sort: p.sort } : {}),
+        ...(p.limit != null ? { limit: Number(p.limit) } : {}),
+        ...(p.filter != null ? { filter: String(p.filter) } : {}),
+    }));
+    add("kill", "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.", {
+        pid: { type: "NUMBER", description: "Process id from processes" },
+        signal: { type: "STRING", enum: ["TERM", "KILL"], description: "TERM (default) or KILL" },
+    }, ["pid"], (p) => ({ kind: 'kill', pid: Number(p.pid), ...(p.signal === 'KILL' || p.signal === 'TERM' ? { signal: p.signal } : {}) }));
+    tools.push({
+        function: {
+            name: "exec",
+            description: "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.",
+            parameters: {
+                type: "OBJECT",
+                properties: {
+                    command: { type: "STRING", description: "Bash command" },
+                    timeoutMs: { type: "NUMBER", description: "Timeout in ms, default 120000; pass more for installs and builds" },
+                },
+                required: ["command"],
+            },
+        },
+        evaluate: async (params) => exec(String(params?.command ?? ""), num(params?.timeoutMs)),
+    });
+    return tools;
+}
+/** `use_desktop`'s result when the person chose not to make a repository for it. */
+export const DESKTOP_DECLINED = "They chose not to use a computer for this. Do it without one if you can.";
+const DESKTOP_CAPTURE = "Everything it captures is attached to the chat for people to see, and comes back to you too. Set video to record the whole job as a captioned video, for when someone asks to see it done. Slower and costlier than the other tools; use it only when the screen matters.";
+/**
+ * The `use_desktop` tool for a Parrot chat: a desktop agent does a job on the
+ * repository's machine. Without a repository it also takes `name`, what to call
+ * the repository the person is asked to make for it.
+ */
+export function desktopTool(repository) {
+    const properties = {
+        goal: { type: "STRING", description: "What the desktop agent should do, in full, with what to capture" },
+        video: { type: "BOOLEAN", description: "Record the whole job as a captioned video" },
+    };
+    if (repository) {
+        return {
+            name: "use_desktop",
+            description: `Do something on the repository's desktop that needs a screen, like using a website. A desktop agent does it and reports back. ${DESKTOP_CAPTURE}`,
+            parameters: { type: "OBJECT", properties, required: ["goal"] },
+        };
+    }
+    return {
+        name: "use_desktop",
+        description: `Do something on a computer that needs a screen, like using a website. This chat has no computer yet, so the person is asked first to make a repository for it: a Linux machine with a desktop. If they agree, a desktop agent does it and reports back; if they don't, do that request without a computer. ${DESKTOP_CAPTURE}`,
+        parameters: {
+            type: "OBJECT",
+            properties: {
+                ...properties,
+                name: { type: "STRING", description: "What to call the repository this makes: two to four words about the task, like eBay Switch search" },
+            },
+            required: ["goal", "name"],
+        },
+    };
+}
+/** Termite's current prices. Anyone can read them, signed in or not. */
+export async function pricing() {
+    const response = await fetch(`${Termite.getURL()}/termite/pricing`, { method: "GET" });
+    if (!response.ok)
+        throw new Error(await response.text());
+    const json = await response.json();
+    return { machinePerHour: Number(json.machinePerHour), storagePerGbMonth: Number(json.storagePerGbMonth) };
+}
+export const Wake = {
+    fromJSON(json) {
+        return {
+            id: String(json.id),
+            reason: json.reason === 'crashed' || json.reason === 'skipped' ? json.reason : 'called',
+            prompt: String(json.prompt ?? ''),
+            started: new Date(json.started),
+            finished: json.finished ? new Date(json.finished) : null,
+            ok: Boolean(json.ok),
+            answer: String(json.answer ?? ''),
+        };
+    },
+};
+/** The times a repository woke its agent, newest first. */
+export async function wakes(authorization, repository, query, opts) {
+    const params = new URLSearchParams({ cursor: String(query.cursor), max: String(query.max) });
+    const response = await fetch(`${Termite.getURL()}/termite/repositories/${repository}/wakes?${params.toString()}`, {
+        method: "GET",
+        headers: {
+            Authorization: "email" in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...(opts?.group ? { Group: opts.group.id } : {}),
+        },
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    return (await response.json()).map(Wake.fromJSON);
+}
+export class MachineRoom extends PageRoom {
+    constructor(ws, authorization, id, hooks, state) {
+        super(ws, authorization, id, hooks, {
+            bootstrap: state?.bootstrap ?? undefined,
+            cursor: state?.cursor ?? undefined,
+            enabledTools: DESKTOP_TOOLS,
+            control: state?.control,
+        }, `${Termite.getURL()}/termite/machine/live`);
+        /** The machine id, the number `connect` takes. */
+        Object.defineProperty(this, "machine", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "repository", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "windows", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        /** Each Files window's folder and view, by window id. */
+        Object.defineProperty(this, "files", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "status", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 'BOOTING'
+        });
+        /** Why the machine failed, when it did. */
+        Object.defineProperty(this, "error", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: ''
+        });
+        /** The repository's name, so a guest who joined by code knows what it is. */
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: ''
+        });
+        /** Its connections go out from a residential address, billed per GB to whoever pays for the machine. */
+        Object.defineProperty(this, "private", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        /** Why private is off when it couldn't turn on or stay on, like a payer out of balance. */
+        Object.defineProperty(this, "privateReason", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: ''
+        });
+        Object.defineProperty(this, "machineHooks", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "calls", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        this.machineHooks = hooks;
+        this.machine = Number(state?.machine?.id ?? 0);
+        this.repository = Number(state?.machine?.repository ?? 0);
+        this.hydrate(state);
+    }
+    /** Apply a connection snapshot `{ machine, bootstrap, cursor, windows }`. */
+    hydrate(state) {
+        if (state?.machine?.status)
+            this.status = state.machine.status;
+        if (state?.machine) {
+            this.error = String(state.machine.error ?? '');
+            this.name = String(state.machine.name ?? '');
+        }
+        this.applyControl(state?.control);
+        if (Array.isArray(state?.windows)) {
+            this.windows.clear();
+            for (const row of state.windows) {
+                const window = Window.fromJSON(row);
+                this.windows.set(window.id, window);
+            }
+        }
+        if (Array.isArray(state?.files)) {
+            this.files.clear();
+            for (const row of state.files)
+                this.files.set(Number(row.window), FilesState.fromJSON(row));
+        }
+        if (state?.private) {
+            this.private = Boolean(state.private.on);
+            this.privateReason = String(state.private.reason ?? '');
+        }
+    }
+    watch(hooks) {
+        this.machineHooks = { ...this.machineHooks, ...hooks };
+        super.watch(hooks);
+    }
+    invokeTool(tool) {
+        if (DESKTOP_KINDS.has(tool.kind))
+            return super.invokeTool(tool);
+        return this.call({ kind: 'tool', tool }, CALL_MS).then((result) => String(result ?? ""));
+    }
+    /** Run a shell command as `agent` in /repository with DISPLAY=:0, so GUI apps open as desktop windows. */
+    exec(command, opts) {
+        const timeoutMs = opts?.timeoutMs ?? EXEC_MS;
+        return this.call({ kind: 'exec', command, timeoutMs }, timeoutMs + 15000).then((result) => ({
+            code: Number(result?.code ?? -1),
+            stdout: String(result?.stdout ?? ""),
+            stderr: String(result?.stderr ?? ""),
+        }));
+    }
+    /** Size the machine's desktop to this seat's screen, clamped to `VIEWPORT`. Only the controller can. */
+    async setViewport(width, height) {
+        await this.call({ kind: 'viewport', ...clampViewport({ width, height }) }, CALL_MS);
+    }
+    /** Open a file in an app on the machine, for everyone to see: text in nano inside an
+     *  xterm, anything else with an installed opener. Only the controller can. */
+    async open(path) {
+        await this.call({ kind: 'open', path }, CALL_MS);
+    }
+    /** Put a Files window on a folder and view for every seat. Only the controller can. */
+    async setFiles(window, files) {
+        await this.call({ kind: 'files', window, path: files.path, view: files.view }, CALL_MS);
+    }
+    /** Save a new revision and shut down. The room closes afterwards. */
+    async stop() {
+        try {
+            await this.call({ kind: 'stop' }, STOP_MS);
+        }
+        catch (err) {
+            // The machine announces it closed before it answers the stop itself.
+            if (this.status !== 'STOPPED')
+                throw err;
+        }
+    }
+    call(call, timeoutMs) {
+        const id = crypto.randomUUID();
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.calls.delete(id);
+                reject(new Error("Machine call timed out."));
+            }, timeoutMs);
+            this.calls.set(id, {
+                resolve: (v) => { clearTimeout(timer); resolve(v); },
+                reject: (e) => { clearTimeout(timer); reject(e); },
+            });
+            this.post({ event: 'machine-call', data: { id, call } });
+        });
+    }
+    parrotTools() {
+        return parrotTools((tool) => this.invokeTool(tool), async (command, timeoutMs) => JSON.stringify(await this.exec(command, { timeoutMs })));
+    }
+    handleEvent(packet) {
+        switch (packet?.event) {
+            case 'machine-status': {
+                if (packet.data?.status)
+                    this.status = packet.data.status;
+                this.machineHooks.onStatus?.(this);
+                return true;
+            }
+            case 'machine-window': {
+                if (!packet.data?.window)
+                    return true;
+                const window = Window.fromJSON(packet.data.window);
+                this.windows.set(window.id, window);
+                this.machineHooks.onWindow?.(this, window);
+                return true;
+            }
+            case 'machine-window-closed': {
+                const id = Number(packet.data?.id);
+                this.windows.delete(id);
+                this.files.delete(id);
+                this.machineHooks.onWindowClosed?.(this, id);
+                return true;
+            }
+            case 'machine-files': {
+                const window = Number(packet.data?.window);
+                const files = FilesState.fromJSON(packet.data);
+                this.files.set(window, files);
+                this.machineHooks.onFiles?.(this, window, files);
+                return true;
+            }
+            case 'machine-private': {
+                this.private = Boolean(packet.data?.on);
+                this.privateReason = String(packet.data?.reason ?? '');
+                this.machineHooks.onPrivate?.(this);
+                return true;
+            }
+            case 'machine-agent-step': {
+                if (packet.data)
+                    this.machineHooks.onAgentStep?.(this, packet.data);
+                return true;
+            }
+            case 'machine-result': {
+                const pending = this.calls.get(packet.data?.id);
+                if (!pending)
+                    return true;
+                this.calls.delete(packet.data.id);
+                if (packet.data?.error)
+                    pending.reject(new Error(String(packet.data.error)));
+                else
+                    pending.resolve(packet.data?.result);
+                return true;
+            }
+            case 'machine-closed': {
+                if (packet.data?.status)
+                    this.status = packet.data.status;
+                this.error = String(packet.data?.error ?? '');
+                this.machineHooks.onStatus?.(this);
+                for (const pending of this.calls.values())
+                    pending.reject(new Error("Machine closed."));
+                this.calls.clear();
+                return super.handleEvent({ event: 'browser-closed', data: {} });
+            }
+            default:
+                return super.handleEvent(packet);
+        }
+    }
+    /**
+     * Boot the repository's machine, or return the one already live, and connect to it.
+     * `private` sends its connections out from a residential address, billed per GB to
+     * whoever pays for the machine; on a live machine it switches it.
+     */
+    static async start(authorization, target, opts) {
+        const response = await fetch(`${Termite.getURL()}/termite/repositories/${target.repository}/machine`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: "email" in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+                ...(opts?.group ? { Group: opts.group.id } : {}),
+            },
+            body: JSON.stringify(opts?.private === undefined ? {} : { private: opts.private }),
+        });
+        if (!response.ok)
+            throw new Error(await response.text());
+        const json = await response.json();
+        return MachineRoom.connect(authorization, { id: Number(json.id) }, opts);
+    }
+    /** Save and shut down a repository's machine without joining its room. For its owner or group members. */
+    static async shutdown(authorization, target, opts) {
+        const response = await fetch(`${Termite.getURL()}/termite/repositories/${target.repository}/machine/stop`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: "email" in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+                ...(opts?.group ? { Group: opts.group.id } : {}),
+            },
+            body: JSON.stringify({}),
+        });
+        if (!response.ok)
+            throw new Error(await response.text());
+    }
+    /** Turn private on or off for a repository's live machine, for its owner or group members.
+     *  Resolves to the machine's private state and, when it couldn't turn on, why. */
+    static async setPrivate(authorization, target, on, opts) {
+        const response = await fetch(`${Termite.getURL()}/termite/repositories/${target.repository}/machine/private`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: "email" in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+                ...(opts?.group ? { Group: opts.group.id } : {}),
+            },
+            body: JSON.stringify({ on }),
+        });
+        if (!response.ok)
+            throw new Error(await response.text());
+        const json = await response.json();
+        return { on: Boolean(json.on), reason: String(json.reason ?? '') };
+    }
+    /** Connect to a live machine by id, or by its `termite:machine:{id}` reference. */
+    static async connect(authorization, target, opts) {
+        return MachineRoom.open({
+            authorization,
+            server: 'id' in target ? `termite:machine:${target.id}` : target.reference,
+            ...(opts?.group ? { group: opts.group.id } : {}),
+        }, opts?.hooks ?? {});
+    }
+    /** Join a machine someone shared with an access code. */
+    static async join(authorization, target, opts) {
+        return MachineRoom.open({ authorization, accessCode: target.accessCode }, opts?.hooks ?? {});
+    }
+    static async open(auth, hooks) {
+        let room;
+        const self = await connectServer(auth, `${Termite.getURL()}/termite/machine/live`, {
+            createRoom: (_endpoint, ws, a, id, state) => {
+                room = new MachineRoom(ws, a, id, hooks, state);
+                return room;
+            },
+            createPresence: (r, data) => {
+                const presence = new Presence(r, data.id, data.profile);
+                presence.update(data);
+                return presence;
+            },
+            onPresence: (r) => r.emitPresence(),
+            onConnection: (r, state) => {
+                const next = r;
+                if (state?.bootstrap)
+                    next.web.ingestBootstrap(state.bootstrap);
+                if (state?.cursor) {
+                    next.cursor = state.cursor;
+                    hooks.onCursor?.(next, next.cursor);
+                }
+                next.hydrate(state);
+            },
+            onEvent: (r, packet) => r.handleEvent(packet),
+            onClosed: (r) => r.emitClosed(),
+        });
+        room.emitPresence();
+        return { room, self };
+    }
+}

package/dist/src/termite/versioning.d.ts

@@ -0,0 +1,94 @@
+import { ApiKey, Credentials } from "../authentification.js";
+import { File } from "../drive.js";
+import { Group } from "../groups.js";
+import type { Schema } from "../shared/schema.js";
+import { Termite } from "./index.js";
+import type { MachineStatus } from "./os.js";
+export type Return = {
+    code: number;
+    description: string;
+    body?: Schema;
+};
+export type Route = {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    description: string;
+    deprecated: boolean;
+    body?: Schema;
+    return: Return[];
+};
+export type Line = {
+    path: string;
+    index: number;
+    kind: 'ADDITION' | 'DELETION';
+};
+export type Change = {
+    /** 1, 2, 3 ... within the repository. This is what `rollback` takes. */
+    revision: number;
+    /** Set when this revision rolled the repository back to an earlier one. */
+    rollback?: number;
+    /** Git commit sha of /repository, '' when the machine never answered. */
+    head: string;
+    lines: Line[];
+    date: Date;
+};
+export declare const Change: {
+    fromJSON(json: any): Change;
+};
+/**
+ * A saved machine: a numbered, principal owned chain of disk revisions on the
+ * one Termite base image. `/repository` inside it is a git folder whose history
+ * is `changes()`. Start it with `OS.MachineRoom.start`.
+ */
+export declare class Repository {
+    readonly id: number;
+    readonly name: string;
+    readonly sizeBytes: number;
+    readonly createdAt: Date;
+    readonly updatedAt: Date;
+    /** Its machine while one is booting, running, or saving. */
+    readonly machine: {
+        id: number;
+        status: MachineStatus;
+    } | null;
+    /** The group that owns it, when it isn't personal. */
+    readonly group?: Group;
+    private readonly authorization;
+    constructor(authorization: Credentials | ApiKey, row: {
+        id: number;
+        name: string;
+        sizeBytes: number;
+        createdAt: Date;
+        updatedAt: Date;
+        machine: {
+            id: number;
+            status: MachineStatus;
+        } | null;
+    }, group?: Group);
+    static fromJSON(json: any, authorization: Credentials | ApiKey, group?: Group): Repository;
+    routes(): Route[];
+    /** Revisions newest first. `cursor: 0` is the latest revision. */
+    changes(query: {
+        cursor: number;
+        max: number;
+    }): Promise<Change[]>;
+    /** A folder gives one `File` per entry, a file gives its own `File`. Nothing downloads until asked. */
+    open(path?: string): Promise<File | File[]>;
+    /** Create or overwrite a file under /repository, running or not. */
+    write(path: string, data: Uint8Array | string, onProgress?: (percent: number) => void): Promise<File>;
+    /** Record a new revision whose disk is exactly `revision`'s. Refused while a machine is live. */
+    rollback(revision: number): Promise<void>;
+    /** Rename it. Returns the repository with its new name. */
+    rename(name: string): Promise<Repository>;
+    delete(): Promise<void>;
+}
+export declare function create(authorization: Credentials | ApiKey, opts?: {
+    name?: string;
+    group?: Group;
+}): Promise<Repository>;
+export declare function get(authorization: Credentials | ApiKey, id: number, opts?: {
+    group?: Group;
+}): Promise<Repository>;
+export declare function list(authorization: Credentials | ApiKey, opts?: {
+    group?: Group;
+}): Promise<Repository[]>;