cloving 1.2.0 → 1.3.0

package/dist/src/relay/relay-control.js

@@ -0,0 +1,24 @@
+import { follow, send } from "../cli/client.js";
+const allowed = new Set([
+    "questions",
+    "status",
+    "events",
+    "decision",
+]);
+export function relayControl(runtimeDirectory) {
+    return (request) => {
+        if (!allowed.has(request.operation))
+            return Promise.reject(new Error(`relay-operation-refused: The phone relay may not send ${request.operation}.`));
+        return send(runtimeDirectory, request);
+    };
+}
+export function relayEvents(runtimeDirectory, stream) {
+    return follow(runtimeDirectory, {
+        request: {
+            operation: "events",
+            parameters: { after: stream.after, follow: true },
+        },
+        onEvent: stream.onEvent,
+        signal: stream.stopped,
+    });
+}

package/dist/src/relay/relay-files.d.ts

@@ -0,0 +1,2 @@
+export declare function readOptional(path: string): Promise<string | undefined>;
+export declare function writePrivate(path: string, value: unknown): Promise<void>;

package/dist/src/relay/relay-files.js

@@ -0,0 +1,23 @@
+import { randomUUID } from "node:crypto";
+import { readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+export async function readOptional(path) {
+    return readFile(path, "utf8").catch((error) => {
+        if (Reflect.get(Object(error), "code") === "ENOENT")
+            return undefined;
+        throw error;
+    });
+}
+export async function writePrivate(path, value) {
+    const temporary = join(path, "..", `.${randomUUID()}.tmp`);
+    try {
+        await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, {
+            mode: 0o600,
+            flag: "wx",
+        });
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}

package/dist/src/relay/relay-heartbeat.d.ts

@@ -0,0 +1,17 @@
+import type { RelayStore } from "./relay-store.ts";
+export interface HeartbeatTiming {
+    readonly intervalMilliseconds: number;
+    readonly firstBackoffMilliseconds: number;
+    readonly longestBackoffMilliseconds: number;
+}
+export declare const heartbeatTiming: HeartbeatTiming;
+export interface HeartbeatContext {
+    readonly phoneDirectory: string;
+    readonly store: RelayStore;
+    readonly lost: () => void;
+    readonly timing: HeartbeatTiming;
+    readonly wait: (milliseconds: number, signal: AbortSignal) => Promise<void>;
+}
+export type BeatOutcome = "beat" | "failed" | "lost" | "replaced" | "unregistered";
+export declare function heartbeat(context: HeartbeatContext, signal?: AbortSignal): Promise<BeatOutcome>;
+export declare function runHeartbeats(context: HeartbeatContext, signal: AbortSignal): Promise<void>;

package/dist/src/relay/relay-heartbeat.js

@@ -0,0 +1,81 @@
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+import { relayRequest } from "./relay-http.js";
+import { readLink } from "./relay-registration.js";
+export const heartbeatTiming = {
+    intervalMilliseconds: 60_000,
+    firstBackoffMilliseconds: 5000,
+    longestBackoffMilliseconds: 300_000,
+};
+function revokedDevices(body) {
+    const devices = typeof body === "object" && body !== null
+        ? Reflect.get(body, "devices")
+        : undefined;
+    if (!Array.isArray(devices))
+        return [];
+    return devices.flatMap((device) => {
+        const deviceId = Reflect.get(Object(device), "device_id");
+        const revokedAt = Reflect.get(Object(device), "revoked_at");
+        return typeof deviceId === "string" && typeof revokedAt === "string"
+            ? [deviceId]
+            : [];
+    });
+}
+async function applyRevocations(context, call) {
+    const { link, signal } = call;
+    if (signal.aborted)
+        return;
+    const reply = await relayRequest(link.origin, {
+        method: "GET",
+        path: "/api/v1/relay/devices",
+        token: link.token,
+        signal,
+    });
+    if (reply.status !== 200)
+        return;
+    const known = new Set((await context.store.devices())
+        .filter((device) => device.removedAt === null)
+        .map((device) => device.deviceId));
+    for (const deviceId of revokedDevices(reply.body))
+        if (known.has(deviceId))
+            await context.store.remove(deviceId);
+}
+async function lostRegistration(context, link) {
+    const current = await readLink(context.phoneDirectory);
+    if (current?.token !== link.token)
+        return "replaced";
+    await context.store.removeAll();
+    await rm(join(context.phoneDirectory, "link.json"), { force: true });
+    context.lost();
+    return "lost";
+}
+export async function heartbeat(context, signal = new AbortController().signal) {
+    const link = await readLink(context.phoneDirectory);
+    if (link === undefined)
+        return "unregistered";
+    const reply = await relayRequest(link.origin, {
+        method: "PUT",
+        path: "/api/v1/relay/daemon/heartbeat",
+        token: link.token,
+        signal,
+    }).catch(() => undefined);
+    if (reply?.status === 401)
+        return lostRegistration(context, link);
+    if (reply === undefined || reply.status >= 300)
+        return "failed";
+    await applyRevocations(context, { link, signal }).catch(() => undefined);
+    return "beat";
+}
+function pause(timing, failures) {
+    if (failures === 0)
+        return timing.intervalMilliseconds;
+    return Math.min(timing.firstBackoffMilliseconds * 2 ** (failures - 1), timing.longestBackoffMilliseconds);
+}
+export async function runHeartbeats(context, signal) {
+    let failures = 0;
+    while (!signal.aborted) {
+        const outcome = await heartbeat(context, signal).catch(() => "failed");
+        failures = outcome === "failed" ? failures + 1 : 0;
+        await context.wait(pause(context.timing, failures), signal);
+    }
+}

package/dist/src/relay/relay-http.d.ts

@@ -0,0 +1,14 @@
+export interface RelayCall {
+    readonly method: "GET" | "POST" | "PUT" | "DELETE";
+    readonly path: string;
+    readonly token?: string;
+    readonly body?: unknown;
+    readonly timeoutMilliseconds?: number;
+    readonly signal?: AbortSignal;
+}
+export interface RelayReply {
+    readonly status: number;
+    readonly body: unknown;
+}
+export declare function relayOrigin(value: string | undefined): string;
+export declare function relayRequest(origin: string, call: RelayCall): Promise<RelayReply>;

package/dist/src/relay/relay-http.js

@@ -0,0 +1,63 @@
+import http from "node:http";
+import https from "node:https";
+export function relayOrigin(value) {
+    const given = value ?? "https://cloving.ai";
+    const url = URL.parse(given);
+    const local = url?.protocol === "http:" && url.hostname === "127.0.0.1";
+    if (url === null ||
+        (url.protocol !== "https:" && !local) ||
+        url.origin !== given ||
+        given.length > 161)
+        throw new Error(`relay-origin-invalid: CLOVING_RELAY_ORIGIN must be an https origin of at most 161 characters, such as https://cloving.ai.`);
+    return url.origin;
+}
+function parsed(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+function headers(call, payload) {
+    return {
+        accept: "application/json",
+        ...(payload === undefined ? {} : { "content-type": "application/json" }),
+        ...(call.token === undefined
+            ? {}
+            : { authorization: `Bearer ${call.token}` }),
+    };
+}
+export function relayRequest(origin, call) {
+    const url = new URL(call.path, origin);
+    const transport = url.protocol === "https:" ? https : http;
+    const payload = call.body === undefined ? undefined : JSON.stringify(call.body);
+    return new Promise((settle, reject) => {
+        const request = transport.request(url, {
+            method: call.method,
+            headers: headers(call, payload),
+            timeout: call.timeoutMilliseconds ?? 30_000,
+            ...(call.signal === undefined ? {} : { signal: call.signal }),
+        }, (response) => {
+            let text = "";
+            response.setEncoding("utf8");
+            response.on("data", (chunk) => {
+                text += chunk;
+            });
+            response.once("end", () => {
+                settle({ status: response.statusCode ?? 0, body: parsed(text) });
+            });
+            const incomplete = () => {
+                if (!response.complete)
+                    reject(new Error("relay-response-incomplete: cloving.ai closed the answer before its end."));
+            };
+            response.once("error", incomplete);
+            response.once("close", incomplete);
+        });
+        request.once("timeout", () => {
+            request.destroy(new Error("relay-timeout: cloving.ai did not answer."));
+        });
+        request.once("error", reject);
+        request.end(payload);
+    });
+}

package/dist/src/relay/relay-registration.d.ts

@@ -0,0 +1,15 @@
+import { type PhoneLink } from "../phone/phone-link.ts";
+import { type DaemonKeys } from "./daemon-keys.ts";
+export interface RegistrationContext {
+    readonly phoneDirectory: string;
+    readonly origin: string;
+    readonly computerName: string;
+}
+export interface Registration {
+    readonly link: PhoneLink;
+    readonly keys: DaemonKeys;
+}
+export declare function readLink(phoneDirectory: string): Promise<PhoneLink | undefined>;
+export declare function storedRegistration(phoneDirectory: string): Promise<Registration | undefined>;
+export declare function forgetRegistration(phoneDirectory: string): Promise<void>;
+export declare function registration(context: RegistrationContext): Promise<Registration>;

package/dist/src/relay/relay-registration.js

@@ -0,0 +1,63 @@
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+import { parsePhoneLink } from "../phone/phone-link.js";
+import { newDaemonKeys, parseDaemonKeys, } from "./daemon-keys.js";
+import { readOptional, writePrivate } from "./relay-files.js";
+import { relayRequest } from "./relay-http.js";
+export function readLink(phoneDirectory) {
+    return readOptional(join(phoneDirectory, "link.json")).then(parsePhoneLink);
+}
+function readKeys(phoneDirectory) {
+    return readOptional(join(phoneDirectory, "daemon-keys.json")).then(parseDaemonKeys);
+}
+export async function storedRegistration(phoneDirectory) {
+    const link = await readLink(phoneDirectory);
+    const keys = await readKeys(phoneDirectory);
+    if (link === undefined || keys === undefined)
+        return undefined;
+    return { link, keys };
+}
+export async function forgetRegistration(phoneDirectory) {
+    await rm(join(phoneDirectory, "link.json"), { force: true });
+}
+function text(body, name) {
+    const value = typeof body === "object" && body !== null
+        ? Reflect.get(body, name)
+        : undefined;
+    if (typeof value !== "string" || value === "")
+        throw new Error(`registration-invalid: cloving.ai sent no ${name}.`);
+    return value;
+}
+async function registered(context, keys) {
+    const reply = await relayRequest(context.origin, {
+        method: "POST",
+        path: "/api/v1/relay/daemons",
+        body: {
+            name: context.computerName,
+            agreement_public_key: keys.agreementPublicKey,
+            signing_public_key: keys.signingPublicKey,
+        },
+    });
+    if (reply.status !== 201)
+        throw new Error(`registration-failed: cloving.ai answered ${String(reply.status)}.`);
+    const link = {
+        daemonId: text(reply.body, "daemon_id"),
+        origin: context.origin,
+        token: text(reply.body, "token"),
+        registeredAt: new Date().toISOString(),
+    };
+    await writePrivate(join(context.phoneDirectory, "link.json"), link);
+    return { link, keys };
+}
+export async function registration(context) {
+    const link = await readLink(context.phoneDirectory);
+    const stored = await readKeys(context.phoneDirectory);
+    if (link !== undefined &&
+        stored !== undefined &&
+        link.origin === context.origin)
+        return { link, keys: stored };
+    const keys = stored ?? newDaemonKeys();
+    if (stored === undefined)
+        await writePrivate(join(context.phoneDirectory, "daemon-keys.json"), keys);
+    return registered(context, keys);
+}

package/dist/src/relay/relay-service.d.ts

@@ -0,0 +1,25 @@
+import { type InboxTiming } from "./answer-inbox.ts";
+import { type WatchTiming } from "./decision-watch.ts";
+import { type HeartbeatTiming } from "./relay-heartbeat.ts";
+export interface RelayPaths {
+    readonly runtimeDirectory: string;
+    readonly phoneDirectory: string;
+}
+export interface RelayOptions extends RelayPaths {
+    readonly origin?: string;
+    readonly computerName?: string;
+    readonly secret?: () => Buffer;
+    readonly heartbeatTiming?: HeartbeatTiming;
+    readonly watchTiming?: WatchTiming;
+    readonly inboxTiming?: InboxTiming;
+}
+export interface Relay {
+    readonly close: () => Promise<void>;
+}
+export declare function computerName(name: string): string;
+export declare function startRelay(options: RelayOptions): Promise<Relay>;
+export interface RelayProgram {
+    readonly stopped: Promise<unknown>;
+    readonly error: (line: string) => void;
+}
+export declare function runRelay(environment: Readonly<Record<string, string | undefined>>, program: RelayProgram): Promise<number>;

package/dist/src/relay/relay-service.js

@@ -0,0 +1,216 @@
+import { randomBytes } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
+import { mkdir } from "node:fs/promises";
+import { hostname } from "node:os";
+import { dirname, join } from "node:path";
+import { inboxTiming, runInbox } from "./answer-inbox.js";
+import { watchDecisions, watchTiming, } from "./decision-watch.js";
+import { followPairing } from "./pairing-follow.js";
+import { pairingSessions, RegistrationEnded, } from "./pairing-session.js";
+import { pairAccept, pairDeny, phoneRemove, phoneReset, result, } from "./phone-operations.js";
+import { listenPhoneSocket } from "./phone-socket.js";
+import { heartbeatTiming, runHeartbeats, } from "./relay-heartbeat.js";
+import { relayControl } from "./relay-control.js";
+import { relayOrigin } from "./relay-http.js";
+import { forgetRegistration, readLink, registration, } from "./relay-registration.js";
+import { openRelayStore } from "./relay-store.js";
+function unknownOperation(request) {
+    return {
+        kind: "error",
+        error: {
+            code: "unknown-operation",
+            detail: `The phone relay has no operation ${request.operation}.`,
+        },
+    };
+}
+function pairingView(open) {
+    if (open === undefined)
+        return null;
+    const request = open.request;
+    return {
+        pairingId: open.pairingId,
+        expiresAt: open.expiresAt,
+        stage: open.stage,
+        request: request === undefined
+            ? null
+            : {
+                deviceId: request.deviceId,
+                name: request.name,
+                platform: request.platform,
+                code: request.code,
+            },
+    };
+}
+async function phoneState(relay) {
+    const link = await readLink(relay.context.phoneDirectory);
+    return result({
+        registered: link !== undefined,
+        daemonId: link?.daemonId ?? null,
+        origin: link?.origin ?? null,
+        pairing: pairingView(relay.sessions.current()),
+        refusal: relay.sessions.refusal(),
+        reason: relay.registration.lost ? "registration-lost" : null,
+        devices: (await relay.store.devices()).map((device) => ({
+            deviceId: device.deviceId,
+            name: device.name,
+            platform: device.platform,
+            pairedAt: device.pairedAt,
+            state: device.state,
+            removedAt: device.removedAt,
+        })),
+    });
+}
+async function opened(relay) {
+    const startedIn = relay.sessions.generation();
+    try {
+        return await relay.sessions.start(await registration(relay.context), startedIn);
+    }
+    catch (error) {
+        if (!(error instanceof RegistrationEnded))
+            throw error;
+        await relay.store.removeAll();
+        await forgetRegistration(relay.context.phoneDirectory);
+        return relay.sessions.start(await registration(relay.context), startedIn);
+    }
+}
+const starts = new WeakMap();
+function sharedStart(relay) {
+    const running = starts.get(relay);
+    if (running !== undefined)
+        return running;
+    const starting = opened(relay).finally(() => starts.delete(relay));
+    starts.set(relay, starting);
+    return starting;
+}
+async function pairStart(relay) {
+    const open = relay.sessions.current() ?? (await sharedStart(relay));
+    relay.registration.lost = false;
+    return result({ link: open.link, expiresAt: open.expiresAt });
+}
+function pairCancel(relay) {
+    relay.sessions.cancel();
+    return Promise.resolve(result({ pairing: null }));
+}
+async function resetAfterStart(relay) {
+    relay.sessions.cancel();
+    await starts.get(relay)?.catch(() => undefined);
+    return phoneReset(relay);
+}
+const operations = {
+    "phone-state": phoneState,
+    "phone-pair-start": pairStart,
+    "phone-pair-cancel": pairCancel,
+    "phone-pair-accept": pairAccept,
+    "phone-pair-deny": pairDeny,
+    "phone-remove": phoneRemove,
+    "phone-reset": resetAfterStart,
+};
+export function computerName(name) {
+    return name.replace(/\.local$/, "").slice(0, 64);
+}
+function deliveringStore(options, opened) {
+    const stop = new AbortController();
+    const reading = new AbortController();
+    const running = opened.run(stop.signal);
+    const context = {
+        runtimeDirectory: options.runtimeDirectory,
+        phoneDirectory: options.phoneDirectory,
+        store: opened,
+        control: relayControl(options.runtimeDirectory),
+        now: () => Date.now(),
+    };
+    const watch = watchDecisions(context, options.watchTiming ?? watchTiming);
+    const answers = runInbox(context, {
+        signal: reading.signal,
+        timing: options.inboxTiming ?? inboxTiming,
+    });
+    return {
+        store: {
+            ...opened,
+            connect: async (deviceId) => {
+                const found = await opened.connect(deviceId);
+                watch.wake();
+                return found;
+            },
+        },
+        close: async () => {
+            reading.abort();
+            await answers;
+            await watch.close();
+            stop.abort();
+            await running;
+        },
+    };
+}
+export async function startRelay(options) {
+    await mkdir(options.runtimeDirectory, { recursive: true, mode: 0o700 });
+    await mkdir(options.phoneDirectory, { recursive: true, mode: 0o700 });
+    const opened = await openRelayStore(options.phoneDirectory);
+    const delivering = deliveringStore(options, opened);
+    const { store } = delivering;
+    const follower = {
+        follow: () => Promise.resolve(),
+    };
+    const relay = {
+        context: {
+            phoneDirectory: options.phoneDirectory,
+            origin: options.origin ?? relayOrigin(undefined),
+            computerName: options.computerName ?? computerName(hostname()),
+        },
+        store,
+        sessions: pairingSessions({
+            secret: options.secret ?? (() => randomBytes(16)),
+            follow: (open) => follower.follow(open),
+        }),
+        registration: { lost: false },
+    };
+    follower.follow = (open) => followPairing(relay, open);
+    const socket = await listenPhoneSocket(join(options.runtimeDirectory, "phone.sock"), (request) => {
+        const operation = operations[request.operation];
+        return operation === undefined
+            ? Promise.resolve(unknownOperation(request))
+            : operation(relay, request.parameters);
+    });
+    const stop = new AbortController();
+    const beating = runHeartbeats({
+        phoneDirectory: options.phoneDirectory,
+        store,
+        timing: options.heartbeatTiming ?? heartbeatTiming,
+        lost: () => {
+            relay.registration.lost = true;
+            relay.sessions.cancel();
+        },
+        wait: (milliseconds, signal) => delay(milliseconds, undefined, { signal }).catch(() => undefined),
+    }, stop.signal);
+    return {
+        close: async () => {
+            stop.abort();
+            relay.sessions.cancel();
+            await beating;
+            await socket.close();
+            await delivering.close();
+            await opened.close();
+        },
+    };
+}
+export async function runRelay(environment, program) {
+    const runtimeDirectory = environment["CLOVING_RUNTIME_DIR"];
+    if (runtimeDirectory === undefined || runtimeDirectory === "") {
+        program.error("runtime-directory-unknown: The phone relay needs CLOVING_RUNTIME_DIR.\n");
+        return 1;
+    }
+    try {
+        const relay = await startRelay({
+            runtimeDirectory,
+            phoneDirectory: join(dirname(runtimeDirectory), "state", "phone"),
+            origin: relayOrigin(environment["CLOVING_RELAY_ORIGIN"]),
+        });
+        await program.stopped;
+        await relay.close();
+        return 0;
+    }
+    catch (error) {
+        program.error(`phone-relay-failed: ${String(Reflect.get(Object(error), "message"))}\n`);
+        return 1;
+    }
+}

package/dist/src/relay/relay-store.d.ts

@@ -0,0 +1,48 @@
+import { type DeviceDelivery, type DeviceEnvelopes, type PostedEnvelope } from "./phone-delivery.ts";
+import { type PhoneDevice } from "./phone-devices.ts";
+import { type InboxWork } from "./phone-inbox.ts";
+import { type OpenDecision } from "./phone-outbox.ts";
+export interface DeliveryOffer {
+    readonly runId: string;
+    readonly promptDigest: string;
+    readonly deviceId: string;
+    readonly envelopes: readonly PostedEnvelope[];
+}
+export interface DeliveryClosing {
+    readonly devices: readonly DeviceEnvelopes[];
+    readonly at: number;
+}
+export interface RelayStore {
+    readonly devices: () => Promise<readonly PhoneDevice[]>;
+    readonly add: (device: PhoneDevice) => Promise<string | undefined>;
+    readonly connect: (deviceId: string) => Promise<boolean>;
+    readonly nextSequence: (deviceId: string) => Promise<number>;
+    readonly remove: (deviceId: string) => Promise<boolean>;
+    readonly removeAll: () => Promise<number>;
+    readonly delivery: RelayDeliveries;
+    readonly inbox: RelayInbox;
+    readonly run: (signal: AbortSignal) => Promise<void>;
+    readonly close: () => Promise<void>;
+}
+export interface RelayDeliveries {
+    readonly offer: (decisionId: string, offer: DeliveryOffer) => Promise<boolean>;
+    readonly close: (decisionId: string, closing: DeliveryClosing) => Promise<boolean>;
+    readonly open: () => Promise<readonly OpenDecision[]>;
+    readonly list: (decisionId: string) => Promise<readonly DeviceDelivery[]>;
+    readonly promptDigest: (decisionId: string) => Promise<string | null>;
+    readonly sweep: () => Promise<number>;
+    readonly drainAt: (now: Date) => Promise<void>;
+}
+export interface RelayInbox {
+    readonly cursor: () => Promise<number>;
+    readonly work: (answerId: string) => Promise<InboxWork | undefined>;
+    readonly record: (work: InboxWork) => Promise<InboxWork>;
+    readonly complete: (done: {
+        readonly answerId: string;
+        readonly sequence: number;
+    }) => Promise<void>;
+}
+export interface RelayStoreOptions {
+    readonly now?: () => number;
+}
+export declare function openRelayStore(phoneDirectory: string, options?: RelayStoreOptions): Promise<RelayStore>;