fauna-api 0.0.0-stage → 1.0.679

package/dist/src/termite/index.js

@@ -0,0 +1,59 @@
+import * as EnvironmentAPI from "./environment.js";
+import * as OSAPI from "./os.js";
+import * as VersioningAPI from "./versioning.js";
+export var Termite;
+(function (Termite) {
+    var PREFIX = 'https://';
+    var IP = 'api.faunakit.com';
+    var PORT = 443;
+    function setRoute(route) {
+        const parts_0 = route.split('//');
+        if (parts_0.length > 1) {
+            PREFIX = parts_0[0] + '//';
+            const parts_1 = parts_0[1].split(':');
+            if (parts_1.length > 1) {
+                IP = parts_1[0];
+                PORT = Number(parts_1[1]);
+            }
+            else {
+                IP = parts_1[0];
+            }
+        }
+        else {
+            const parts_1 = parts_0[0].split(':');
+            if (parts_1.length > 1) {
+                IP = parts_1[0];
+                PORT = Number(parts_1[1]);
+            }
+            else {
+                IP = parts_1[0];
+            }
+        }
+    }
+    Termite.setRoute = setRoute;
+    function getIP() {
+        return IP;
+    }
+    Termite.getIP = getIP;
+    function getPort() {
+        return PORT;
+    }
+    Termite.getPort = getPort;
+    function getRoute() {
+        return IP + ':' + PORT;
+    }
+    Termite.getRoute = getRoute;
+    function getURL() {
+        return PREFIX + IP + ':' + PORT;
+    }
+    Termite.getURL = getURL;
+    async function ping() {
+        const start = Date.now();
+        await fetch(`${getURL()}/`);
+        return Date.now() - start;
+    }
+    Termite.ping = ping;
+    Termite.Environment = EnvironmentAPI;
+    Termite.OS = OSAPI;
+    Termite.Versioning = VersioningAPI;
+})(Termite || (Termite = {}));

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

@@ -0,0 +1,326 @@
+/**
+ * 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 { ApiKey, Credentials } from "../authentification.js";
+import { Group } from "../groups.js";
+import { PageRoom, type BrowserRoomHooks, type BrowserTool } from "../marmot/browser.js";
+import type { Function, Tool } from "../parrot/generative.js";
+import { Authorization, Presence } from "../shared/server.js";
+import { Termite } from "./index.js";
+import type { Repository } from "./versioning.js";
+export type WindowTool = {
+    kind: 'windows';
+} | {
+    kind: 'focus';
+    window: number;
+} | {
+    kind: 'place';
+    window: number;
+    x: number;
+    y: number;
+} | {
+    kind: 'resize';
+    window: number;
+    width: number;
+    height: number;
+} | {
+    kind: 'close';
+    window: number;
+}
+/** Load a Web window's page again, after its files change. Previews follow their file on their own. */
+ | {
+    kind: 'reload';
+    window: number;
+}
+/** A web window at `url`; a files window at `path` (a folder of /repository); a preview of the
+ *  file at `path`, which follows the file as it changes; or a terminal, running `command` in
+ *  view and staying open at a prompt when it ends. */
+ | {
+    kind: 'open';
+    app: 'web' | 'files' | 'file' | 'terminal';
+    url?: string;
+    path?: string;
+    command?: string;
+}
+/** A chord like ['ctrl', 's']. Focuses `window` first when given. */
+ | {
+    kind: 'key';
+    keys: string[];
+    window?: number;
+};
+/** Paths are relative to /repository, and `/` is the repository root. */
+export type FileTool = {
+    kind: 'list';
+    path?: string;
+    pattern?: string;
+} | {
+    kind: 'grep';
+    pattern: string;
+    path?: string;
+    glob?: string;
+    ignoreCase?: boolean;
+    context?: number;
+    output?: 'files' | 'lines' | 'count';
+    max?: number;
+} | {
+    kind: 'read';
+    path: string;
+    line?: number;
+    before?: number;
+    after?: number;
+} | {
+    kind: 'write';
+    path: string;
+    text: string;
+} | {
+    kind: 'replace';
+    path: string;
+    old: string;
+    new: string;
+    all?: boolean;
+} | {
+    kind: 'insert';
+    path: string;
+    after: number;
+    text: string;
+} | {
+    kind: 'remove';
+    path: string;
+    start: number;
+    end: number;
+};
+/** The guest's processes. `kill` stops only the agent user's own, never the machine's or the desktop's. */
+export type ProcessTool = {
+    kind: 'processes';
+    sort?: 'cpu' | 'memory';
+    limit?: number;
+    filter?: string;
+} | {
+    kind: 'kill';
+    pid: number;
+    signal?: 'TERM' | 'KILL';
+};
+/** Pointer and keyboard input on the desktop. No executeJavascript, which would run on the
+ *  desktop page itself, and no search or exit, which belong to a web page's agent. */
+export type DesktopTool = Exclude<BrowserTool, {
+    kind: 'executeJavascript' | 'search' | 'exit';
+}>;
+export type MachineTool = DesktopTool | WindowTool | FileTool | ProcessTool;
+/** Metadata for one desktop window. Its pixels live in the desktop HTML. */
+export type Window = {
+    /** Same id as the element's data-window and the window tools. */
+    id: number;
+    kind: 'app' | 'web' | 'files' | 'preview';
+    /** WM_CLASS for apps ('xterm'), 'web', 'files', or 'preview'. */
+    app: string;
+    title: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    focused: boolean;
+};
+export declare const Window: {
+    fromJSON(json: any): Window;
+};
+/** The folder and view a Files window is on. The controller sets it; every seat follows. */
+export type FilesState = {
+    path: string;
+    view: 'list' | 'cozy';
+};
+export declare const FilesState: {
+    fromJSON(json: any): FilesState;
+};
+export type MachineStatus = 'BOOTING' | 'RUNNING' | 'STOPPING' | 'STOPPED' | 'FAILED';
+export type Viewport = {
+    width: number;
+    height: number;
+};
+/** The smallest and largest desktop a machine draws. The largest is the guest's X screen. */
+export declare const VIEWPORT: {
+    min: Viewport;
+    max: Viewport;
+};
+/** A desktop size inside `VIEWPORT`, in whole pixels. */
+export declare function clampViewport(size: Viewport): Viewport;
+export type MachineRoomHooks = BrowserRoomHooks<DesktopTool> & Partial<{
+    /** A window opened, moved, resized, retitled, or changed focus. */
+    onWindow(room: MachineRoom, window: Window): void;
+    onWindowClosed(room: MachineRoom, id: number): void;
+    /** A Files window's folder or view changed. */
+    onFiles(room: MachineRoom, window: number, files: FilesState): void;
+    onStatus(room: MachineRoom): void;
+    /** Private turned on or off, or couldn't stay on (`privateReason` says why). */
+    onPrivate(room: MachineRoom): void;
+    /** An agent holding the machine took a step. */
+    onAgentStep(room: MachineRoom, step: AgentStep): void;
+}>;
+/** One tool call of an agent working the machine: the tool, with what, and what came back. A turn
+ *  with several calls arrives as several steps. Args and result are capped at about 2 KB; larger
+ *  args arrive as `{ truncated }`. */
+export type AgentStep = {
+    /** The agent's id, as in the room's control state. */
+    agent: string;
+    /** The turn, counting from 1. */
+    step: number;
+    /** The call's place in its turn, from 0. */
+    call: number;
+    tool: string;
+    args: Record<string, unknown>;
+    result: string;
+    /** The turn's model time and usage ride on its first call, so totals add up. */
+    modelMs: number;
+    toolMs: number;
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+    };
+};
+/**
+ * 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 declare function parrotTools(invoke: (tool: MachineTool) => Promise<string>, exec: (command: string, timeoutMs?: number) => Promise<string>): Tool[];
+/** `use_desktop`'s result when the person chose not to make a repository for it. */
+export declare const DESKTOP_DECLINED = "They chose not to use a computer for this. Do it without one if you can.";
+/**
+ * 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 declare function desktopTool(repository?: Repository | null): Function;
+/** What Termite charges, in dollars. */
+export type Pricing = {
+    /** A running machine, per hour. */
+    machinePerHour: number;
+    /** A repository's stored files, per GB a month. */
+    storagePerGbMonth: number;
+};
+/** Termite's current prices. Anyone can read them, signed in or not. */
+export declare function pricing(): Promise<Pricing>;
+/**
+ * One time a repository woke its machine agent: its code ran wake.sh (`called`),
+ * entry.sh crashed (`crashed`), or the hourly limit left it out (`skipped`).
+ */
+export type Wake = {
+    id: string;
+    reason: 'called' | 'crashed' | 'skipped';
+    /** What the agent was told: wake.sh's prompt, or how entry.sh ended. */
+    prompt: string;
+    started: Date;
+    /** When the woken run ended, or null while it works. */
+    finished: Date | null;
+    ok: boolean;
+    /** What the agent said when it finished, or why it stopped. */
+    answer: string;
+};
+export declare const Wake: {
+    fromJSON(json: any): Wake;
+};
+/** The times a repository woke its agent, newest first. */
+export declare function wakes(authorization: Credentials | ApiKey, repository: number, query: {
+    cursor: number;
+    max: number;
+}, opts?: {
+    group?: Group;
+}): Promise<Wake[]>;
+export declare class MachineRoom extends PageRoom<DesktopTool> {
+    /** The machine id, the number `connect` takes. */
+    readonly machine: number;
+    readonly repository: number;
+    readonly windows: Map<number, Window>;
+    /** Each Files window's folder and view, by window id. */
+    readonly files: Map<number, FilesState>;
+    status: MachineStatus;
+    /** Why the machine failed, when it did. */
+    error: string;
+    /** The repository's name, so a guest who joined by code knows what it is. */
+    name: string;
+    /** Its connections go out from a residential address, billed per GB to whoever pays for the machine. */
+    private: boolean;
+    /** Why private is off when it couldn't turn on or stay on, like a payer out of balance. */
+    privateReason: string;
+    private machineHooks;
+    private calls;
+    constructor(ws: WebSocket, authorization: Authorization, id: string, hooks: MachineRoomHooks, state?: any);
+    /** Apply a connection snapshot `{ machine, bootstrap, cursor, windows }`. */
+    hydrate(state: any): void;
+    watch(hooks: MachineRoomHooks): void;
+    invokeTool(tool: MachineTool): Promise<string>;
+    /** Run a shell command as `agent` in /repository with DISPLAY=:0, so GUI apps open as desktop windows. */
+    exec(command: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<{
+        code: number;
+        stdout: string;
+        stderr: string;
+    }>;
+    /** Size the machine's desktop to this seat's screen, clamped to `VIEWPORT`. Only the controller can. */
+    setViewport(width: number, height: number): Promise<void>;
+    /** 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. */
+    open(path: string): Promise<void>;
+    /** Put a Files window on a folder and view for every seat. Only the controller can. */
+    setFiles(window: number, files: FilesState): Promise<void>;
+    /** Save a new revision and shut down. The room closes afterwards. */
+    stop(): Promise<void>;
+    private call;
+    parrotTools(): Tool[];
+    handleEvent(packet: any): boolean;
+    /**
+     * 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 start(authorization: Credentials | ApiKey, target: {
+        repository: number;
+    }, opts?: {
+        group?: Group;
+        hooks?: MachineRoomHooks;
+        private?: boolean;
+    }): Promise<{
+        room: MachineRoom;
+        self: Presence;
+    }>;
+    /** Save and shut down a repository's machine without joining its room. For its owner or group members. */
+    static shutdown(authorization: Credentials | ApiKey, target: {
+        repository: number;
+    }, opts?: {
+        group?: Group;
+    }): Promise<void>;
+    /** 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 setPrivate(authorization: Credentials | ApiKey, target: {
+        repository: number;
+    }, on: boolean, opts?: {
+        group?: Group;
+    }): Promise<{
+        on: boolean;
+        reason: string;
+    }>;
+    /** Connect to a live machine by id, or by its `termite:machine:{id}` reference. */
+    static connect(authorization: Credentials | ApiKey, target: {
+        id: number;
+    } | {
+        reference: string;
+    }, opts?: {
+        group?: Group;
+        hooks?: MachineRoomHooks;
+    }): Promise<{
+        room: MachineRoom;
+        self: Presence;
+    }>;
+    /** Join a machine someone shared with an access code. */
+    static join(authorization: Credentials | ApiKey, target: {
+        accessCode: string;
+    }, opts?: {
+        hooks?: MachineRoomHooks;
+    }): Promise<{
+        room: MachineRoom;
+        self: Presence;
+    }>;
+    private static open;
+}