cloving 1.1.0 → 1.3.0

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>;

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

@@ -0,0 +1,131 @@
+import { chmod, open } from "node:fs/promises";
+import { join } from "node:path";
+import { createRuntime, Rejected, } from "solid-objects";
+import { sqlite } from "solid-objects/database/sqlite";
+import { postEnvelopes } from "./envelope-post.js";
+import { deviceRemoved, PhoneDelivery, postEnvelopesEffect, } from "./phone-delivery.js";
+import { PhoneDevices } from "./phone-devices.js";
+import { PhoneInbox } from "./phone-inbox.js";
+import { outboxIdentity, PhoneOutbox, } from "./phone-outbox.js";
+const relayPrincipal = Object.freeze({ principal: "phone-relay" });
+const devicesIdentity = "phone";
+const inboxIdentity = "phone";
+const relayActors = new Set([
+    PhoneDevices.actorType,
+    PhoneDelivery.actorType,
+    PhoneOutbox.actorType,
+    PhoneInbox.actorType,
+]);
+function authorized(input) {
+    return (relayActors.has(input.actorType) &&
+        input.authorizationContext === relayPrincipal);
+}
+function destroyable(input) {
+    return (input.actorType === PhoneDelivery.actorType &&
+        input.authorizationContext === relayPrincipal);
+}
+function postRefusal(devices, deviceId) {
+    const device = devices.find((item) => item.deviceId === deviceId);
+    if (device === undefined || device.removedAt !== null)
+        return deviceRemoved;
+    return device.state === "connected" ? null : "device-not-connected";
+}
+function relayDeliveries(runtime) {
+    const outbox = runtime
+        .ref(PhoneOutbox, outboxIdentity)
+        .with({ authorizationContext: relayPrincipal });
+    const delivery = (decisionId) => runtime
+        .ref(PhoneDelivery, decisionId)
+        .with({ authorizationContext: relayPrincipal });
+    return {
+        offer: async (decisionId, offer) => {
+            await outbox.track({ decisionId, runId: offer.runId });
+            return delivery(decisionId).offer({
+                deviceId: offer.deviceId,
+                envelopes: offer.envelopes,
+                promptDigest: offer.promptDigest,
+            });
+        },
+        close: async (decisionId, closing) => {
+            const closed = await delivery(decisionId).close(closing);
+            await outbox.untrack({ decisionId });
+            return closed;
+        },
+        open: async () => [...(await outbox.decisions)],
+        list: async (decisionId) => [...(await delivery(decisionId).deliveries)],
+        promptDigest: async (decisionId) => delivery(decisionId).promptDigest,
+        sweep: async () => {
+            const retired = [...(await outbox.retired)];
+            for (const decisionId of retired) {
+                await runtime
+                    .ref(PhoneDelivery, decisionId)
+                    .destroy({ authorizationContext: relayPrincipal });
+                await outbox.forget({ decisionId });
+            }
+            return retired.length;
+        },
+        drainAt: async (now) => {
+            await runtime.testing.runDueReminders({ now });
+            await runtime.testing.drain({ roles: ["actors", "effects"] });
+        },
+    };
+}
+function relayInbox(runtime) {
+    const inbox = runtime
+        .ref(PhoneInbox, inboxIdentity)
+        .with({ authorizationContext: relayPrincipal });
+    return {
+        cursor: async () => inbox.cursor,
+        work: async (answerId) => (await inbox.work).find((item) => item.answerId === answerId),
+        record: (work) => inbox.record(work),
+        complete: (done) => inbox.complete(done),
+    };
+}
+export async function openRelayStore(phoneDirectory, options = {}) {
+    const path = join(phoneDirectory, "relay.sqlite3");
+    await (await open(path, "a", 0o600)).close();
+    await chmod(path, 0o600);
+    const runtime = createRuntime({
+        database: sqlite({ path }),
+        authorizeMessage: authorized,
+        authorizeQuery: authorized,
+        authorizeDestroy: destroyable,
+    });
+    await runtime.install();
+    runtime.register(PhoneDevices);
+    runtime.register(PhoneDelivery);
+    runtime.register(PhoneOutbox);
+    runtime.register(PhoneInbox);
+    const devices = runtime
+        .ref(PhoneDevices, devicesIdentity)
+        .with({ authorizationContext: relayPrincipal });
+    const now = options.now ?? (() => Date.now());
+    runtime.registerEffect(postEnvelopesEffect, async (request) => {
+        const refusal = postRefusal(await devices.devices, request["deviceId"]);
+        if (refusal !== null)
+            return { at: now(), failure: refusal };
+        return postEnvelopes({ phoneDirectory, now }, request);
+    });
+    return {
+        devices: async () => [...(await devices.devices)],
+        add: async (device) => {
+            try {
+                await devices.add({ device });
+                return undefined;
+            }
+            catch (error) {
+                if (error instanceof Rejected)
+                    return error.code.replaceAll("_", "-");
+                throw error;
+            }
+        },
+        connect: (deviceId) => devices.connect({ deviceId }),
+        nextSequence: (deviceId) => devices.nextSequence({ deviceId }),
+        remove: (deviceId) => devices.remove({ deviceId, removedAt: new Date().toISOString() }),
+        removeAll: () => devices.removeAll({ removedAt: new Date().toISOString() }),
+        delivery: relayDeliveries(runtime),
+        inbox: relayInbox(runtime),
+        run: (signal) => runtime.run(signal),
+        close: () => runtime.close(),
+    };
+}

package/dist/src/relay/sealed-post.d.ts

@@ -0,0 +1,25 @@
+import { type Fields, type Reply, type ServiceRequest } from "../protocol.ts";
+import type { EnvelopeTarget } from "./decision-envelopes.ts";
+import { type Envelope } from "./envelope.ts";
+import type { PostedEnvelope } from "./phone-delivery.ts";
+import type { PhoneDevice } from "./phone-devices.ts";
+import type { Registration } from "./relay-registration.ts";
+import type { RelayStore } from "./relay-store.ts";
+export interface CheckContext {
+    readonly phoneDirectory: string;
+    readonly store: RelayStore;
+    readonly control: (request: ServiceRequest) => Promise<Reply>;
+    readonly now: () => number;
+}
+export interface Sealing {
+    readonly registration: Registration;
+    readonly device: PhoneDevice;
+    readonly decisionId: string;
+    readonly issuedAt: string;
+    readonly expiresAt: string;
+    readonly build: (target: EnvelopeTarget) => Envelope;
+}
+export declare function rows(value: unknown): readonly Fields[];
+export declare function resultOf(context: CheckContext, request: ServiceRequest): Promise<Fields | undefined>;
+export declare function envelopeExpiry(gateExpiry: unknown, issued: number): string;
+export declare function sealedPost(context: CheckContext, sealing: Sealing): Promise<PostedEnvelope>;

package/dist/src/relay/sealed-post.js

@@ -0,0 +1,52 @@
+import { randomBytes } from "node:crypto";
+import { record, } from "../protocol.js";
+import { collapseId, sealEnvelope, } from "./envelope.js";
+const pushes = {
+    preview: "alert",
+    full: "none",
+    closed: "passive",
+    receipt: "none",
+};
+const collapsing = new Set(["preview", "closed"]);
+const envelopeLifetimeMilliseconds = 7 * 86_400_000 - 3_600_000;
+export function rows(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((item) => {
+        const fields = record(item);
+        return fields === undefined ? [] : [fields];
+    });
+}
+export async function resultOf(context, request) {
+    const reply = await context.control(request);
+    return reply.kind === "result" ? reply.result : undefined;
+}
+export function envelopeExpiry(gateExpiry, issued) {
+    const limit = issued + envelopeLifetimeMilliseconds;
+    const gate = Date.parse(String(gateExpiry));
+    return new Date(Number.isNaN(gate) ? limit : Math.min(gate, limit)).toISOString();
+}
+export async function sealedPost(context, sealing) {
+    const { registration, device } = sealing;
+    const envelope = sealing.build({
+        daemonId: registration.link.daemonId,
+        deviceId: device.deviceId,
+        sequence: await context.store.nextSequence(device.deviceId),
+        issuedAt: sealing.issuedAt,
+        expiresAt: sealing.expiresAt,
+    });
+    const sealed = sealEnvelope(registration.keys, {
+        envelope,
+        agreementPublicKey: device.agreementPublicKey,
+    });
+    return {
+        envelopeId: randomBytes(16).toString("base64url"),
+        kind: envelope.kind,
+        ciphertext: sealed.toString("base64url"),
+        expiresAt: sealing.expiresAt,
+        push: pushes[envelope.kind],
+        collapseId: collapsing.has(envelope.kind)
+            ? collapseId(registration.keys, sealing.decisionId)
+            : null,
+    };
+}

package/dist/src/relay.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/relay.js

@@ -0,0 +1,8 @@
+import { runRelay } from "./relay/relay-service.js";
+process.exitCode = await runRelay(process.env, {
+    stopped: new Promise((settle) => {
+        process.once("SIGTERM", settle);
+        process.once("SIGINT", settle);
+    }),
+    error: (line) => process.stderr.write(line),
+});

package/dist/src/report-statistics.d.ts

@@ -0,0 +1,50 @@
+export interface ReportDatum {
+    readonly at: number;
+    readonly value: number | null;
+    readonly evidence: Readonly<Record<string, unknown>>;
+}
+export interface ReportWindow {
+    readonly start: number;
+    readonly end: number;
+    readonly observedSince: number | null;
+}
+interface MetricInput {
+    readonly data: readonly ReportDatum[] | null;
+    readonly window: ReportWindow;
+    readonly aggregation: "count" | "median";
+}
+export declare function reportMedian(values: readonly number[]): number | null;
+export declare function reportMetric(input: MetricInput): {
+    evidence: Readonly<Record<string, unknown>>[];
+    mark?: string;
+    status: string;
+    value: number | null;
+    comparisonValue: number | null;
+    baseline: {
+        evidence: Readonly<Record<string, unknown>>[];
+        history: string;
+        days: number;
+        median: null;
+        band: null;
+    } | {
+        evidence: Readonly<Record<string, unknown>>[];
+        history: string;
+        days: number;
+        median: number;
+        band: null;
+    } | {
+        evidence: Readonly<Record<string, unknown>>[];
+        history: string;
+        days: number;
+        median: number;
+        band: {
+            low: number;
+            high: number;
+        };
+    };
+};
+export declare function outsideReportBand(value: number | null, band: {
+    readonly low: number;
+    readonly high: number;
+} | null): boolean;
+export {};

package/dist/src/report-statistics.js

@@ -0,0 +1,70 @@
+export function reportMedian(values) {
+    if (values.length === 0)
+        return null;
+    const sorted = values.toSorted((left, right) => left - right);
+    const middle = Math.floor(sorted.length / 2);
+    return ((sorted[middle] ?? 0) / 2 +
+        (sorted[Math.ceil(sorted.length / 2) - 1] ?? 0) / 2);
+}
+function selected(data, window) {
+    return data.filter((datum) => datum.at >= window.start && datum.at < window.end);
+}
+function aggregate(data, aggregation) {
+    if (data.some((datum) => datum.value === null))
+        return null;
+    const values = data.flatMap((datum) => datum.value === null ? [] : [datum.value]);
+    return aggregation === "count"
+        ? values.reduce((sum, value) => sum + value, 0)
+        : reportMedian(values);
+}
+function baseline(input) {
+    const day = 86_400_000;
+    const origin = input.window.observedSince;
+    const samples = [];
+    const evidence = [];
+    for (let index = 1; index <= 7; index += 1) {
+        const end = input.window.start - (index - 1) * day;
+        const start = end - day;
+        if (origin === null || origin > start || input.data === null)
+            continue;
+        const data = selected(input.data, { start, end });
+        const value = aggregate(data, input.aggregation);
+        if (value === null)
+            continue;
+        samples.push(value);
+        evidence.push(...data.map((datum) => datum.evidence));
+    }
+    return { ...historySummary(samples), evidence };
+}
+function historySummary(samples) {
+    const median = reportMedian(samples);
+    const deviation = median === null
+        ? null
+        : reportMedian(samples.map((value) => Math.abs(value - median)));
+    if (samples.length < 5 || median === null || deviation === null)
+        return { history: "short", days: samples.length, median: null, band: null };
+    const band = { low: median - 3 * deviation, high: median + 3 * deviation };
+    if (!Number.isFinite(band.low) || !Number.isFinite(band.high))
+        return { history: "unavailable", days: samples.length, median, band: null };
+    return { history: "available", days: samples.length, median, band };
+}
+export function reportMetric(input) {
+    const data = selected(input.data ?? [], input.window);
+    const value = input.data === null ? null : aggregate(data, input.aggregation);
+    const comparisonValue = value !== null && input.aggregation === "count"
+        ? (value * 86_400_000) / (input.window.end - input.window.start)
+        : value;
+    const history = baseline(input);
+    const outside = outsideReportBand(comparisonValue, history.band);
+    return {
+        status: value === null ? "unavailable" : "available",
+        value,
+        comparisonValue,
+        baseline: history,
+        ...(outside ? { mark: "outside" } : {}),
+        evidence: data.map((datum) => datum.evidence),
+    };
+}
+export function outsideReportBand(value, band) {
+    return (value !== null && band !== null && (value < band.low || value > band.high));
+}

package/dist/src/report.d.ts

@@ -0,0 +1,171 @@
+import { type ReportDatum } from "./report-statistics.ts";
+import type { Fields } from "./protocol.ts";
+export declare const reportOutcomes: readonly ["completed", "partial", "blocked", "failed", "cancelled"];
+export type ReportOutcome = (typeof reportOutcomes)[number];
+export interface ReportCompletion {
+    readonly runId: string;
+    readonly sequence: number;
+    readonly at: number;
+    readonly outcome: ReportOutcome;
+}
+export interface ReportCost {
+    readonly runId: string;
+    readonly turns: readonly {
+        readonly operationId: string;
+        readonly costUsd: number | null;
+        readonly estimatedCostUsd?: number;
+    }[] | null;
+}
+interface ReportInput {
+    readonly since: number;
+    readonly now: number;
+    readonly completions: readonly ReportCompletion[] | null;
+    readonly observedSince?: number | null;
+    readonly costs?: readonly ReportCost[];
+    readonly github?: {
+        readonly observedSince?: number | null;
+        readonly issues: readonly ReportDatum[] | null;
+        readonly pulls: readonly ReportDatum[] | null;
+        readonly sources: Fields;
+    };
+}
+export declare function loopReport(input: ReportInput): {
+    sources: {
+        daemon: {
+            status: string;
+        };
+        github: Readonly<Record<string, unknown>>;
+    };
+    coverage: {
+        ci: {
+            status: string;
+            reason: string;
+        };
+        flow: {
+            status: string;
+            reason: string;
+        };
+        quality: {
+            status: string;
+            reason: string;
+        };
+        operator: {
+            status: string;
+            reason: string;
+        };
+        phases: {
+            status: string;
+            reason: string;
+        };
+        fixRounds: {
+            status: string;
+            reason: string;
+        };
+        leadTime: {
+            status: string;
+            reason: string;
+        };
+        ticketClosureHistory: {
+            status: string;
+            reason: string;
+        };
+        completedTicketCosts: {
+            status: string;
+            reason: string;
+        };
+    };
+    metrics: Record<string, {
+        evidence: Readonly<Record<string, unknown>>[];
+        mark?: string;
+        status: string;
+        value: number | null;
+        comparisonValue: number | null;
+        baseline: {
+            evidence: Readonly<Record<string, unknown>>[];
+            history: string;
+            days: number;
+            median: null;
+            band: null;
+        } | {
+            evidence: Readonly<Record<string, unknown>>[];
+            history: string;
+            days: number;
+            median: number;
+            band: null;
+        } | {
+            evidence: Readonly<Record<string, unknown>>[];
+            history: string;
+            days: number;
+            median: number;
+            band: {
+                low: number;
+                high: number;
+            };
+        };
+    }>;
+    runCosts: {
+        mark?: string;
+        baseline: {
+            evidence: Readonly<Record<string, unknown>>[];
+            history: string;
+            days: number;
+            median: null;
+            band: null;
+        } | {
+            evidence: Readonly<Record<string, unknown>>[];
+            history: string;
+            days: number;
+            median: number;
+            band: null;
+        } | {
+            evidence: Readonly<Record<string, unknown>>[];
+            history: string;
+            days: number;
+            median: number;
+            band: {
+                low: number;
+                high: number;
+            };
+        };
+        runId: string;
+        outcome: "completed" | "failed" | "cancelled" | "partial" | "blocked";
+        completedAt: number;
+        costUsd: number | null;
+        turns: readonly {
+            readonly operationId: string;
+            readonly costUsd: number | null;
+            readonly estimatedCostUsd?: number;
+        }[] | null;
+        evidence: {
+            runId: string;
+            sequence: number;
+        };
+    }[];
+    schemaVersion: number;
+    kind: string;
+    window: {
+        start: number;
+        end: number;
+        hours: number;
+    };
+    semantics: {
+        tickets: string;
+        costs: string;
+    };
+};
+export declare function reportRunCosts(completions: readonly ReportCompletion[], costs: readonly ReportCost[]): {
+    runId: string;
+    outcome: "completed" | "failed" | "cancelled" | "partial" | "blocked";
+    completedAt: number;
+    costUsd: number | null;
+    turns: readonly {
+        readonly operationId: string;
+        readonly costUsd: number | null;
+        readonly estimatedCostUsd?: number;
+    }[] | null;
+    evidence: {
+        runId: string;
+        sequence: number;
+    };
+}[];
+export {};

package/dist/src/report.js

@@ -0,0 +1,119 @@
+import { reportMetric, outsideReportBand, } from "./report-statistics.js";
+export const reportOutcomes = [
+    "completed",
+    "partial",
+    "blocked",
+    "failed",
+    "cancelled",
+];
+function outcomeMetrics(input, window) {
+    return Object.fromEntries(reportOutcomes.map((outcome) => {
+        const data = input.completions === null
+            ? null
+            : input.completions
+                .filter((event) => event.outcome === outcome)
+                .map((event) => ({
+                at: event.at,
+                value: 1,
+                evidence: { runId: event.runId, sequence: event.sequence },
+            }));
+        return [
+            `runs.${outcome}`,
+            reportMetric({ data, window, aggregation: "count" }),
+        ];
+    }));
+}
+function metricCollection(input, window) {
+    const costs = reportRunCosts(input.completions ?? [], input.costs ?? []);
+    const metrics = outcomeMetrics(input, window);
+    const costMetric = reportMetric({
+        data: input.completions === null
+            ? null
+            : costs.map((cost) => ({
+                at: cost.completedAt,
+                value: cost.costUsd,
+                evidence: cost.evidence,
+            })),
+        window,
+        aggregation: "median",
+    });
+    metrics["cost.medianRunUsd"] = costMetric;
+    const githubWindow = {
+        ...window,
+        observedSince: input.github?.observedSince ?? null,
+    };
+    metrics["tickets.completed"] = reportMetric({
+        data: input.github?.issues ?? null,
+        window: githubWindow,
+        aggregation: "count",
+    });
+    metrics["pullRequests.merged"] = reportMetric({
+        data: input.github?.pulls ?? null,
+        window: githubWindow,
+        aggregation: "count",
+    });
+    const runCosts = costs
+        .filter((cost) => cost.completedAt >= window.start && cost.completedAt < window.end)
+        .map((cost) => ({
+        ...cost,
+        baseline: costMetric.baseline,
+        ...(outsideReportBand(cost.costUsd, costMetric.baseline.band)
+            ? { mark: "outside" }
+            : {}),
+    }));
+    return { metrics, runCosts };
+}
+export function loopReport(input) {
+    const end = input.now;
+    const start = end - input.since * 3_600_000;
+    const window = { start, end, observedSince: input.observedSince ?? null };
+    const unavailable = { status: "unavailable", reason: "not-implemented" };
+    return {
+        schemaVersion: 1,
+        kind: "loop-report",
+        window: { start, end, hours: input.since },
+        semantics: {
+            tickets: "currently-closed-completed",
+            costs: "lifetime-turn-cost-attributed-at-run-end",
+        },
+        ...metricCollection(input, window),
+        sources: {
+            daemon: {
+                status: input.completions === null ? "unavailable" : "available",
+            },
+            github: input.github?.sources ?? {
+                issues: { status: "unavailable" },
+                pulls: { status: "unavailable" },
+                history: { status: "unavailable" },
+            },
+        },
+        coverage: {
+            ci: unavailable,
+            flow: unavailable,
+            quality: unavailable,
+            operator: unavailable,
+            phases: unavailable,
+            fixRounds: unavailable,
+            leadTime: unavailable,
+            ticketClosureHistory: unavailable,
+            completedTicketCosts: unavailable,
+        },
+    };
+}
+export function reportRunCosts(completions, costs) {
+    return completions.map((event) => {
+        const turns = costs.find((cost) => cost.runId === event.runId)?.turns ?? null;
+        const known = turns !== null && turns.every((turn) => turn.costUsd !== null);
+        const total = known
+            ? turns.reduce((sum, turn) => sum + (turn.costUsd ?? 0), 0)
+            : null;
+        return {
+            runId: event.runId,
+            outcome: event.outcome,
+            completedAt: event.at,
+            costUsd: total !== null && Number.isFinite(total) ? total : null,
+            turns,
+            evidence: { runId: event.runId, sequence: event.sequence },
+        };
+    });
+}

package/dist/src/repository-identity.d.ts

@@ -0,0 +1,4 @@
+export declare function repositoryFileName(identity: {
+    readonly name: string;
+    readonly sha256: string;
+}): string;