cloving 1.2.0 → 1.3.0

package/dist/src/private-config.schema.json

@@ -0,0 +1,263 @@
+{
+    "type": "object",
+    "properties": {
+        "version": {
+            "const": 1
+        },
+        "checks": {
+            "type": "object",
+            "properties": {
+                "beforeMerge": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "required": {
+                    "type": "array",
+                    "items": {
+                        "type": "string",
+                        "pattern": "\\S"
+                    }
+                }
+            },
+            "additionalProperties": false
+        },
+        "tickets": {
+            "type": "object",
+            "properties": {
+                "command": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "nextCommand": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                }
+            },
+            "additionalProperties": false
+        },
+        "queue": {
+            "type": "object",
+            "properties": {
+                "everySeconds": {
+                    "type": "integer",
+                    "minimum": 10,
+                    "maximum": 3600
+                },
+                "lanes": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 4
+                }
+            },
+            "additionalProperties": false
+        },
+        "harness": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "pattern": "^[a-z][a-z0-9-]{0,63}$"
+                },
+                "kind": {
+                    "enum": ["file", "shell"]
+                },
+                "path": {
+                    "type": "string"
+                },
+                "command": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "turn": {
+                    "type": "array",
+                    "minItems": 1,
+                    "prefixItems": [
+                        {
+                            "type": "string",
+                            "pattern": "^(?!\\{prompt\\}$)[^\\u0000]+$"
+                        }
+                    ],
+                    "items": {
+                        "type": "string",
+                        "pattern": "^[^\\u0000]*$"
+                    },
+                    "contains": {
+                        "const": "{prompt}"
+                    },
+                    "minContains": 0,
+                    "maxContains": 1
+                },
+                "output": {
+                    "const": "text"
+                }
+            },
+            "additionalProperties": false
+        },
+        "profiles": {
+            "type": "object",
+            "propertyNames": {
+                "pattern": "^[A-Za-z0-9_-]{1,119}$"
+            },
+            "additionalProperties": {
+                "type": "object",
+                "properties": {
+                    "harness": {
+                        "type": "string",
+                        "pattern": "^[a-z][a-z0-9-]{0,63}$"
+                    },
+                    "env": {
+                        "type": "object",
+                        "propertyNames": {
+                            "pattern": "^(?!(GH_TOKEN|GITHUB_TOKEN|GH_ENTERPRISE_TOKEN|GITHUB_ENTERPRISE_TOKEN|GH_CONFIG_DIR)$)[A-Za-z_][A-Za-z0-9_]*$"
+                        },
+                        "additionalProperties": {
+                            "type": "string",
+                            "pattern": "^[^\\u0000]*$"
+                        }
+                    },
+                    "allowedTools": {
+                        "type": "array",
+                        "items": {
+                            "type": "string",
+                            "pattern": "^[^\\u0000]*$"
+                        }
+                    },
+                    "workflows": {
+                        "type": "array",
+                        "items": {
+                            "type": "string",
+                            "pattern": "^[^\\u0000]*$"
+                        }
+                    },
+                    "model": {
+                        "type": "string",
+                        "pattern": "^[^\\u0000]*$"
+                    },
+                    "permissionMode": {
+                        "type": "string",
+                        "pattern": "^[^\\u0000]*$"
+                    },
+                    "maxBudgetUsd": {
+                        "type": "number",
+                        "exclusiveMinimum": 0
+                    }
+                },
+                "additionalProperties": false
+            }
+        },
+        "fallbackModels": {
+            "type": "array",
+            "maxItems": 3,
+            "items": {
+                "type": "string",
+                "pattern": "\\S"
+            }
+        },
+        "tokenPrices": {
+            "type": "object",
+            "additionalProperties": {
+                "type": "object",
+                "properties": {
+                    "input": {
+                        "type": "number",
+                        "minimum": 0
+                    },
+                    "cachedInput": {
+                        "type": "number",
+                        "minimum": 0
+                    },
+                    "output": {
+                        "type": "number",
+                        "minimum": 0
+                    }
+                },
+                "additionalProperties": false,
+                "required": ["input", "cachedInput", "output"]
+            }
+        },
+        "privateTexts": {
+            "type": "array",
+            "items": {
+                "type": "string"
+            }
+        },
+        "notify": {
+            "type": "object",
+            "properties": {
+                "command": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                }
+            },
+            "additionalProperties": false
+        },
+        "watch": {
+            "type": "object",
+            "properties": {
+                "port": {
+                    "anyOf": [
+                        {
+                            "type": "integer",
+                            "minimum": 0,
+                            "maximum": 65535
+                        },
+                        {
+                            "const": "off"
+                        }
+                    ]
+                },
+                "actions": {
+                    "enum": ["on", "off"]
+                }
+            },
+            "additionalProperties": false
+        },
+        "selfUpdate": {
+            "type": "object",
+            "properties": {
+                "everySeconds": {
+                    "type": "integer",
+                    "minimum": 30,
+                    "maximum": 3600
+                }
+            },
+            "additionalProperties": false
+        },
+        "github": {
+            "type": "object",
+            "properties": {
+                "command": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                }
+            },
+            "additionalProperties": false
+        },
+        "workflows": {
+            "type": "object",
+            "properties": {
+                "folder": {
+                    "type": "string",
+                    "pattern": "^/"
+                }
+            },
+            "additionalProperties": false
+        }
+    },
+    "additionalProperties": false,
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "title": "Cloving private settings",
+    "required": ["version"]
+}

package/dist/src/project-config.schema.json

@@ -0,0 +1,65 @@
+{
+    "type": "object",
+    "properties": {
+        "version": {
+            "const": 1
+        },
+        "checks": {
+            "type": "object",
+            "properties": {
+                "beforeMerge": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "required": {
+                    "type": "array",
+                    "items": {
+                        "type": "string",
+                        "pattern": "\\S"
+                    }
+                }
+            },
+            "additionalProperties": false
+        },
+        "tickets": {
+            "type": "object",
+            "properties": {
+                "command": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "nextCommand": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                }
+            },
+            "additionalProperties": false
+        },
+        "queue": {
+            "type": "object",
+            "properties": {
+                "everySeconds": {
+                    "type": "integer",
+                    "minimum": 10,
+                    "maximum": 3600
+                },
+                "lanes": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 4
+                }
+            },
+            "additionalProperties": false
+        }
+    },
+    "additionalProperties": false,
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "title": "Cloving project settings",
+    "required": ["version"]
+}

package/dist/src/project-settings.d.ts

@@ -0,0 +1,19 @@
+import { type Configuration } from "./configuration-schema.ts";
+import type { TurnProfiles } from "./turn-profile.ts";
+import type { TokenPrices } from "./token-prices.ts";
+export type SettingSource = "environment" | "private" | "project";
+export type SettingValue = string | number | readonly string[] | TurnProfiles | TokenPrices;
+export declare const settingVariables: Readonly<Record<string, string>>;
+export declare function absoluteWorkflowFolder(folder: string | undefined): string | undefined;
+export declare function configurationRoot(environment: Readonly<NodeJS.ProcessEnv>, home: string): string;
+export declare function parseConfiguration(contents: string | undefined, scope: "project" | "private"): Partial<Configuration>;
+export declare function configurationValues(values: Partial<Configuration>): Readonly<Record<string, SettingValue>>;
+export declare function resolveSettings(environment: Readonly<NodeJS.ProcessEnv>, files: {
+    readonly project: string | undefined;
+    readonly private: string | undefined;
+}): {
+    readonly environment: Readonly<NodeJS.ProcessEnv>;
+    readonly profiles: TurnProfiles;
+    readonly harness?: Configuration["harness"];
+    readonly sources: Readonly<Record<string, SettingSource>>;
+};

package/dist/src/project-settings.js

@@ -0,0 +1,131 @@
+import { configuration } from "./configuration-schema.js";
+export const settingVariables = {
+    "checks.beforeMerge": "CLOVING_CHECK_COMMAND",
+    "checks.required": "CLOVING_REQUIRED_CHECKS",
+    "tickets.command": "CLOVING_TICKET_COMMAND",
+    "tickets.nextCommand": "CLOVING_NEXT_COMMAND",
+    "queue.everySeconds": "CLOVING_QUEUE_SECONDS",
+    "queue.lanes": "CLOVING_QUEUE_LANES",
+    "harness.name": "CLOVING_WORKER",
+    fallbackModels: "CLOVING_FALLBACK_MODELS",
+    tokenPrices: "CLOVING_TOKEN_PRICES",
+    privateTexts: "CLOVING_PRIVATE_TEXTS",
+    "notify.command": "CLOVING_NOTIFY_COMMAND",
+    "watch.port": "CLOVING_WATCH_PORT",
+    "watch.actions": "CLOVING_WATCH_ACTIONS",
+    "selfUpdate.everySeconds": "CLOVING_SELF_UPDATE_SECONDS",
+    "github.command": "CLOVING_GH_COMMAND",
+    "workflows.folder": "CLOVING_WORKFLOW_FOLDER",
+};
+const environmentOnly = [
+    "CLOVING_RUNTIME_DIR",
+    "CLOVING_OWNERSHIP_LEASE_SECONDS",
+    "CLOVING_HOST_BOUND",
+    "CLOVING_WATCH_REPOSITORY",
+    "CLOVING_COMMANDS",
+    "CLOVING_COMMAND_SECONDS",
+    "CLOVING_SCHEDULES",
+    "CLOVING_PHONE_RELAY",
+    "CLOVING_RELAY_ORIGIN",
+];
+export function absoluteWorkflowFolder(folder) {
+    if (folder === undefined || folder.startsWith("/"))
+        return folder;
+    throw new Error("invalid-setting: CLOVING_WORKFLOW_FOLDER must be an absolute path");
+}
+export function configurationRoot(environment, home) {
+    const configured = environment["XDG_CONFIG_HOME"];
+    return configured?.startsWith("/")
+        ? configured
+        : `${environment["HOME"] ?? home}/.config`;
+}
+export function parseConfiguration(contents, scope) {
+    if (contents === undefined)
+        return {};
+    let value;
+    try {
+        value = JSON.parse(contents);
+    }
+    catch {
+        throw new Error(`invalid-config-json: ${scope}`);
+    }
+    return configuration(value, scope);
+}
+export function configurationValues(values) {
+    const entries = [];
+    const groups = {
+        checks: values.checks,
+        tickets: values.tickets,
+        queue: values.queue,
+        harness: values.harness,
+        notify: values.notify,
+        watch: values.watch,
+        selfUpdate: values.selfUpdate,
+        github: values.github,
+        workflows: values.workflows,
+    };
+    for (const [name, group] of Object.entries(groups)) {
+        if (group === undefined)
+            continue;
+        for (const [child, item] of Object.entries(group))
+            entries.push([`${name}.${child}`, item]);
+    }
+    const direct = {
+        profiles: values.profiles,
+        fallbackModels: values.fallbackModels,
+        tokenPrices: values.tokenPrices,
+        privateTexts: values.privateTexts,
+    };
+    for (const [name, value] of Object.entries(direct))
+        if (value !== undefined)
+            entries.push([name, value]);
+    return Object.fromEntries(entries);
+}
+function encoded(value) {
+    return typeof value === "string" ? value : JSON.stringify(value);
+}
+function harnessCommandMapping(name) {
+    if (name === "opencode")
+        return { "harness.command": "CLOVING_OPENCODE_COMMAND" };
+    if (name === "grok")
+        return { "harness.command": "CLOVING_GROK_COMMAND" };
+    if (name === "codex")
+        return { "harness.command": "CLOVING_CODEX_COMMAND" };
+    if (name === "gemini")
+        return { "harness.command": "CLOVING_GEMINI_COMMAND" };
+    if (name === undefined || name === "claude")
+        return { "harness.command": "CLOVING_CLAUDE_COMMAND" };
+    return {};
+}
+export function resolveSettings(environment, files) {
+    const project = configurationValues(parseConfiguration(files.project, "project"));
+    const privateConfiguration = parseConfiguration(files.private, "private");
+    const privateFile = configurationValues(privateConfiguration);
+    const values = { ...project, ...privateFile };
+    const resolved = { ...environment };
+    const sources = {};
+    const mapped = {
+        ...settingVariables,
+        ...harnessCommandMapping(values["harness.name"]),
+        profiles: "CLOVING_PROFILES",
+        ...Object.fromEntries(environmentOnly.map((name) => [name, name])),
+    };
+    for (const field of Object.keys(values))
+        sources[field] = Object.hasOwn(privateFile, field) ? "private" : "project";
+    for (const [field, variable] of Object.entries(mapped)) {
+        const value = values[field];
+        if (environment[variable] !== undefined)
+            sources[field] = "environment";
+        else if (field !== "profiles" && value !== undefined)
+            resolved[variable] = encoded(value);
+    }
+    const profiles = privateConfiguration.profiles ?? {};
+    return {
+        environment: resolved,
+        profiles,
+        sources,
+        ...(privateConfiguration.harness === undefined
+            ? {}
+            : { harness: privateConfiguration.harness }),
+    };
+}

package/dist/src/relay/answer-check.d.ts

@@ -0,0 +1,24 @@
+import { type Fields } from "../protocol.ts";
+import type { PhoneDevice } from "./phone-devices.ts";
+export interface SignedAnswerMessage {
+    readonly payload: string;
+    readonly signature: string;
+}
+export interface AnswerScope {
+    readonly daemonId: string;
+    readonly routedDeviceId: string;
+    readonly devices: readonly PhoneDevice[];
+    readonly now: number;
+    readonly sentPromptDigest: string | null;
+}
+export type AnswerVerdict = {
+    readonly kind: "decision";
+    readonly decisionId: string;
+    readonly parameters: Fields;
+} | {
+    readonly kind: "refused";
+    readonly code: string;
+    readonly decisionId: string | null;
+};
+export declare function answerDecisionId(message: SignedAnswerMessage): string | null;
+export declare function answerVerdict(message: SignedAnswerMessage, scope: AnswerScope): AnswerVerdict;

package/dist/src/relay/answer-check.js

@@ -0,0 +1,145 @@
+import { createHash, verify } from "node:crypto";
+import { record } from "../protocol.js";
+import { publicKeyObject } from "./pairing-checks.js";
+const textNames = [
+    "daemonId",
+    "deviceId",
+    "decisionId",
+    "command",
+    "subjectDigest",
+    "promptDigest",
+    "commandId",
+    "signedAt",
+    "keyClass",
+];
+const countNames = ["expectedRevision", "generation"];
+const commands = new Set(["answer", "approve", "deny"]);
+const keyClasses = new Set(["answer", "approval"]);
+const ageLimitMilliseconds = 10 * 60_000;
+function payloadFields(payload) {
+    try {
+        return record(JSON.parse(payload));
+    }
+    catch {
+        return undefined;
+    }
+}
+function optionalText(value) {
+    return value === null || typeof value === "string";
+}
+function wellFormed(fields) {
+    return (fields["version"] === 1 &&
+        fields["kind"] === "answer" &&
+        textNames.every((name) => typeof fields[name] === "string") &&
+        countNames.every((name) => {
+            const value = fields[name];
+            return Number.isSafeInteger(value) && Number(value) >= 1;
+        }) &&
+        commands.has(String(fields["command"])) &&
+        keyClasses.has(String(fields["keyClass"])) &&
+        !Number.isNaN(Date.parse(String(fields["signedAt"]))));
+}
+function parsedAnswer(message) {
+    const fields = payloadFields(message.payload);
+    if (fields === undefined || !wellFormed(fields))
+        return undefined;
+    const text = fields["text"] ?? null;
+    const textDigest = fields["textDigest"] ?? null;
+    if (!optionalText(text) || !optionalText(textDigest))
+        return undefined;
+    const value = (name) => String(fields[name]);
+    return {
+        daemonId: value("daemonId"),
+        deviceId: value("deviceId"),
+        decisionId: value("decisionId"),
+        command: value("command"),
+        text,
+        textDigest,
+        expectedRevision: Number(fields["expectedRevision"]),
+        generation: Number(fields["generation"]),
+        subjectDigest: value("subjectDigest"),
+        promptDigest: value("promptDigest"),
+        commandId: value("commandId"),
+        signedAt: Date.parse(value("signedAt")),
+        keyClass: value("keyClass"),
+    };
+}
+function deviceRefusal(device) {
+    if (device === undefined)
+        return "device-unknown";
+    if (device.removedAt !== null)
+        return "device-revoked";
+    if (device.state !== "connected")
+        return "device-not-connected";
+    return undefined;
+}
+function signatureValid(checking) {
+    const { answer, device, message } = checking;
+    const key = publicKeyObject(answer.keyClass === "approval"
+        ? device.approvalPublicKey
+        : device.answerPublicKey);
+    if (key === undefined)
+        return false;
+    try {
+        return verify("sha256", Buffer.from(message.payload), { key, dsaEncoding: "ieee-p1363" }, Buffer.from(message.signature, "base64url"));
+    }
+    catch {
+        return false;
+    }
+}
+function digestOf(text) {
+    return `sha256:${createHash("sha256").update(text).digest("hex")}`;
+}
+const checks = [
+    (checking) => (signatureValid(checking) ? undefined : "signature-invalid"),
+    ({ answer }) => answer.command !== "answer" && answer.keyClass !== "approval"
+        ? "approval-key-required"
+        : undefined,
+    ({ answer, scope }) => Math.abs(scope.now - answer.signedAt) > ageLimitMilliseconds
+        ? "answer-too-old"
+        : undefined,
+    ({ answer, scope }) => scope.sentPromptDigest === answer.promptDigest
+        ? undefined
+        : "prompt-changed",
+    ({ answer }) => {
+        const expected = answer.text === null ? null : digestOf(answer.text);
+        return answer.textDigest === expected ? undefined : "answer-invalid";
+    },
+];
+function decisionParameters(answer) {
+    return {
+        command: answer.command,
+        reference: answer.decisionId,
+        ...(answer.text === null ? {} : { text: answer.text }),
+        expectedRevision: answer.expectedRevision,
+        generation: answer.generation,
+        subjectDigest: answer.subjectDigest,
+        commandId: answer.commandId,
+        actor: `device:${answer.deviceId}`,
+    };
+}
+export function answerDecisionId(message) {
+    const decisionId = payloadFields(message.payload)?.["decisionId"];
+    return typeof decisionId === "string" ? decisionId : null;
+}
+export function answerVerdict(message, scope) {
+    const answer = parsedAnswer(message);
+    if (answer === undefined ||
+        answer.daemonId !== scope.daemonId ||
+        answer.deviceId !== scope.routedDeviceId)
+        return { kind: "refused", code: "answer-invalid", decisionId: null };
+    const device = scope.devices.find((item) => item.deviceId === answer.deviceId);
+    const refusal = deviceRefusal(device) ??
+        (device === undefined
+            ? undefined
+            : checks
+                .map((check) => check({ answer, device, message, scope }))
+                .find((code) => code !== undefined));
+    if (refusal !== undefined)
+        return { kind: "refused", code: refusal, decisionId: answer.decisionId };
+    return {
+        kind: "decision",
+        decisionId: answer.decisionId,
+        parameters: decisionParameters(answer),
+    };
+}

package/dist/src/relay/answer-inbox.d.ts

@@ -0,0 +1,15 @@
+import { type CheckContext } from "./sealed-post.ts";
+export interface InboxReading {
+    readonly waitSeconds: number;
+    readonly signal: AbortSignal;
+}
+export interface InboxTiming {
+    readonly waitSeconds: number;
+    readonly retryMilliseconds: number;
+}
+export declare const inboxTiming: InboxTiming;
+export declare function readAnswers(context: CheckContext, reading: InboxReading): Promise<boolean>;
+export declare function runInbox(context: CheckContext, running: {
+    readonly signal: AbortSignal;
+    readonly timing: InboxTiming;
+}): Promise<void>;