cloving 1.1.0 → 1.3.0

package/dist/src/daemon/workflow-schedules.d.ts

@@ -0,0 +1,27 @@
+import type { WorkerPort } from "../service/worker-port.ts";
+import type { DeclaredWorkflow } from "../workflow-declaration.ts";
+interface ScheduleSettings {
+    readonly directory: string;
+    readonly runtimeDirectory: string;
+    readonly declarations?: readonly DeclaredWorkflow[];
+    readonly scheduleClock?: () => number;
+    readonly submit: WorkerPort["submit"];
+}
+export declare function scheduledDeclarations(settings: {
+    readonly declarations?: readonly DeclaredWorkflow[];
+    readonly schedules?: unknown;
+}, limits?: {
+    readonly repository: string;
+    readonly documentBytes: number;
+}): {
+    readonly kind: "configured";
+    readonly declarations: readonly DeclaredWorkflow[];
+} | {
+    readonly kind: "refused";
+    readonly reason: string;
+    readonly detail: string;
+};
+export declare function workflowSchedules(settings: ScheduleSettings): Promise<{
+    readonly stop: () => Promise<void>;
+}>;
+export {};

package/dist/src/daemon/workflow-schedules.js

@@ -0,0 +1,185 @@
+import { join } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { mutate } from "../cli/client.js";
+import { record } from "../protocol.js";
+import { runIdentity } from "../service/submission-handler.js";
+import { configuredSchedules } from "../workflow-schedule.js";
+import { declaredInput } from "./declared-input.js";
+import { scheduleJournal, } from "./schedule-journal.js";
+export function scheduledDeclarations(settings, limits) {
+    try {
+        const declarations = settings.declarations ?? [];
+        const configured = configuredSchedules(declarations, settings.schedules === undefined ? {} : settings.schedules);
+        if (limits !== undefined &&
+            Object.entries(configured).some(([workflowId, schedule]) => Buffer.byteLength(JSON.stringify(declaredInput(limits.repository, {
+                commandId: commandId(workflowId, 1),
+                submission: schedule.input,
+            }))) > limits.documentBytes))
+            throw new Error("invalid-schedule-input");
+        return {
+            kind: "configured",
+            declarations: declarations.map((entry) => {
+                const schedule = Object.hasOwn(configured, entry.workflowId)
+                    ? configured[entry.workflowId]
+                    : undefined;
+                return schedule === undefined ? entry : { ...entry, schedule };
+            }),
+        };
+    }
+    catch (error) {
+        return {
+            kind: "refused",
+            reason: "schedule-rejected",
+            detail: String(error),
+        };
+    }
+}
+function commandId(workflowId, slot) {
+    return `schedule:${workflowId}:${String(slot)}`;
+}
+async function request(settings, request) {
+    const interrupted = Promise.withResolvers();
+    const interrupt = () => {
+        interrupted.resolve(undefined);
+    };
+    settings.signal.addEventListener("abort", interrupt, { once: true });
+    try {
+        settings.signal.throwIfAborted();
+        return await mutate(settings.runtimeDirectory, {
+            request,
+            signal: interrupted.promise,
+        });
+    }
+    finally {
+        settings.signal.removeEventListener("abort", interrupt);
+    }
+}
+async function pending(settings, entry) {
+    settings.signal.throwIfAborted();
+    const { workflowId, progress } = entry;
+    const { pending: planned, ...rest } = progress;
+    if (planned === undefined)
+        return progress;
+    const identity = commandId(workflowId, progress.lastSlot);
+    if (planned.kind === "skip") {
+        const receipt = await settings.submit({
+            kind: "record-schedule-skip",
+            commandId: `skip:${identity}`,
+            runId: planned.runId,
+            workflowId,
+            slot: progress.lastSlot,
+        });
+        if (receipt.kind !== "accepted" && receipt.kind !== "duplicate")
+            throw new Error("schedule-skip-not-recorded");
+        return rest;
+    }
+    const reply = await request(settings, {
+        operation: "run",
+        parameters: {
+            workflowId,
+            source: "declared",
+            submission: planned.input,
+            commandId: identity,
+        },
+    });
+    if (reply.kind === "error")
+        throw new Error(reply.error.code);
+    return { ...rest, activeCommandId: identity };
+}
+async function active(settings, progress) {
+    if (progress.activeCommandId === undefined)
+        return undefined;
+    const runId = runIdentity(progress.activeCommandId);
+    const reply = await request(settings, {
+        operation: "status",
+        parameters: { runId },
+    });
+    if (reply.kind === "error")
+        throw new Error(reply.error.code);
+    const run = record(reply.result["run"]);
+    if (typeof run?.["state"] !== "string")
+        throw new Error("invalid-schedule-run");
+    if (run["condition"] === "cancelling")
+        return runId;
+    return ["completed", "failed", "cancelled"].includes(run["state"])
+        ? undefined
+        : runId;
+}
+async function tick(settings, journal) {
+    const now = (settings.scheduleClock ?? Date.now)();
+    for (const declaration of settings.declarations ?? []) {
+        settings.signal.throwIfAborted();
+        const { workflowId, schedule } = declaration;
+        if (schedule === undefined)
+            continue;
+        let progress = journal.entries.get(workflowId);
+        if (progress === undefined)
+            throw new Error("missing-schedule-state");
+        if (progress.pending !== undefined) {
+            progress = await pending(settings, { workflowId, progress });
+            journal.entries.set(workflowId, progress);
+            await journal.save();
+        }
+        if (now < progress.nextAt)
+            continue;
+        const runId = await active(settings, progress);
+        const planned = runId === undefined
+            ? { kind: "run", input: schedule.input }
+            : { kind: "skip", runId };
+        const elapsed = Math.floor((now - progress.nextAt) / (schedule.everySeconds * 1000)) + 1;
+        progress = {
+            ...progress,
+            lastSlot: progress.lastSlot + elapsed,
+            nextAt: progress.nextAt + elapsed * schedule.everySeconds * 1000,
+            pending: planned,
+        };
+        journal.entries.set(workflowId, progress);
+        await journal.save();
+        journal.entries.set(workflowId, await pending(settings, { workflowId, progress }));
+        await journal.save();
+    }
+}
+async function initialized(settings) {
+    const journal = await scheduleJournal(join(settings.directory, "state"));
+    const now = (settings.scheduleClock ?? Date.now)();
+    for (const declaration of settings.declarations ?? []) {
+        const { workflowId, schedule } = declaration;
+        if (schedule === undefined)
+            continue;
+        const prior = journal.entries.get(workflowId);
+        if (prior?.everySeconds === schedule.everySeconds)
+            continue;
+        journal.entries.set(workflowId, {
+            ...prior,
+            everySeconds: schedule.everySeconds,
+            lastSlot: prior?.lastSlot ?? 0,
+            nextAt: now + schedule.everySeconds * 1000,
+        });
+    }
+    await journal.save();
+    return journal;
+}
+export async function workflowSchedules(settings) {
+    if (!(settings.declarations ?? []).some((entry) => entry.schedule !== undefined))
+        return { stop: () => Promise.resolve() };
+    const journal = await initialized(settings);
+    const stopping = new AbortController();
+    const stopped = () => stopping.signal.aborted;
+    const running = (async () => {
+        while (!stopped()) {
+            await delay(250, undefined, { signal: stopping.signal }).catch(() => undefined);
+            if (stopped())
+                return;
+            await tick({ ...settings, signal: stopping.signal }, journal);
+        }
+    })().catch((error) => {
+        if (!stopped())
+            process.stderr.write(`Schedules stopped: ${String(error)}\n`);
+    });
+    return {
+        stop: async () => {
+            stopping.abort();
+            await running;
+        },
+    };
+}

package/dist/src/decision-visibility.d.ts

@@ -0,0 +1,2 @@
+import type { Fields } from "./protocol.ts";
+export declare function operationalDecision(decision: Fields, workflowId: string): Fields;

package/dist/src/decision-visibility.js

@@ -0,0 +1,10 @@
+export function operationalDecision(decision, workflowId) {
+    if (workflowId !== "analyze-chats")
+        return decision;
+    return {
+        ...decision,
+        prompt: "Private analysis question. Run cloving questions to view it.",
+        context: [],
+        feedback: [],
+    };
+}

package/dist/src/decision-wait.d.ts

@@ -0,0 +1 @@
+export declare function decisionToken(runId: string, gateId: string): string;

package/dist/src/decision-wait.js

@@ -0,0 +1,3 @@
+export function decisionToken(runId, gateId) {
+    return `cloving-decision/v1/${encodeURIComponent(runId)}/${encodeURIComponent(gateId)}`;
+}

package/dist/src/delivery-backoff.d.ts

@@ -0,0 +1 @@
+export declare const deliveryBackoffMilliseconds: readonly [0, 60000, 300000, 900000, 3600000];

package/dist/src/delivery-backoff.js

@@ -0,0 +1,3 @@
+export const deliveryBackoffMilliseconds = [
+    0, 60_000, 300_000, 900_000, 3_600_000,
+];

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

@@ -0,0 +1,24 @@
+import { type SubmissionContract } from "./submission.ts";
+export declare const doctorCodes: readonly ["git-repository", "node-version", "harnesses", "default-harness", "gh-login", "github-origin", "greptile-review", "settings-files", "runtime-directory", "service", "ticket-command", "next-command", "check-command", "queue-interval", "private-texts"];
+export type DoctorCode = (typeof doctorCodes)[number];
+export interface DoctorObservation {
+    readonly result: "ok" | "fail" | "skip";
+    readonly detail: string;
+}
+export interface DoctorCheck extends DoctorObservation {
+    readonly code: DoctorCode;
+    readonly required: boolean;
+    readonly fix: string;
+}
+export declare const doctorFixes: Readonly<Record<DoctorCode, string>>;
+export declare function doctorExitCode(checks: readonly DoctorCheck[]): number;
+export interface DoctorWorkflow {
+    readonly queue?: boolean;
+    readonly scope: "bundled" | "project" | "user";
+    readonly workflowId: string;
+    readonly capabilities: readonly string[];
+    readonly input?: SubmissionContract;
+}
+export declare function requiredDoctorCodes(workflows: readonly DoctorWorkflow[], options: {
+    readonly queueSeconds: string | undefined;
+}): readonly DoctorCode[];

package/dist/src/doctor-report.js

@@ -0,0 +1,70 @@
+import { hasTicketField } from "./submission.js";
+export const doctorCodes = [
+    "git-repository",
+    "node-version",
+    "harnesses",
+    "default-harness",
+    "gh-login",
+    "github-origin",
+    "greptile-review",
+    "settings-files",
+    "runtime-directory",
+    "service",
+    "ticket-command",
+    "next-command",
+    "check-command",
+    "queue-interval",
+    "private-texts",
+];
+export const doctorFixes = {
+    "git-repository": "Change to the repository, or run: git init",
+    "node-version": "Install a supported Node version: nvm install 26 && nvm use 26",
+    harnesses: "Install a harness: npm install -g @anthropic-ai/claude-code",
+    "default-harness": "Install a harness: npm install -g @anthropic-ai/claude-code; select it: CLOVING_WORKER=claude cloving doctor; clear command overrides: unset CLOVING_CLAUDE_COMMAND CLOVING_CODEX_COMMAND; edit private harness.command if configured; for another harness: cloving config set harness.turn '[...]'",
+    "gh-login": "Log in with the configured GitHub command: gh auth login",
+    "github-origin": "Set a GitHub origin: git remote add origin git@github.com:OWNER/REPO.git || git remote set-url origin git@github.com:OWNER/REPO.git",
+    "greptile-review": "Install the Greptile app at https://github.com/apps/greptile, then open a first pull request: gh pr create",
+    "settings-files": "Fix the project JSON: ${EDITOR:-vi} .cloving/config.json; for private JSON, edit <config>/cloving/projects/<repository-id>.json",
+    "runtime-directory": 'Select a private writable runtime: CLOVING_RUNTIME_DIR="$HOME/.local/state/cloving/doctor/run" cloving doctor',
+    service: "Start the service: cloving start",
+    "ticket-command": "Set tickets.command to an executable list: ${EDITOR:-vi} .cloving/config.json",
+    "next-command": "Set tickets.nextCommand to an executable list: ${EDITOR:-vi} .cloving/config.json",
+    "check-command": "Set checks.beforeMerge to an executable list: ${EDITOR:-vi} .cloving/config.json",
+    "queue-interval": "Set an interval from 10 to 3600: CLOVING_QUEUE_SECONDS=30 cloving doctor",
+    "private-texts": `Set a nonblank private text: CLOVING_PRIVATE_TEXTS='["TEXT TO KEEP PRIVATE"]' cloving doctor`,
+};
+export function doctorExitCode(checks) {
+    return checks.some((check) => check.required && check.result !== "ok")
+        ? 1
+        : 0;
+}
+export function requiredDoctorCodes(workflows, options) {
+    const codes = new Set([
+        "git-repository",
+        "node-version",
+        "default-harness",
+        "settings-files",
+        "runtime-directory",
+    ]);
+    if (workflows.some((workflow) => workflow.capabilities.includes("github"))) {
+        codes.add("gh-login");
+        codes.add("github-origin");
+    }
+    const bundled = workflows
+        .filter((workflow) => workflow.scope === "bundled")
+        .map((workflow) => workflow.workflowId);
+    const issue = bundled.includes("develop-issue");
+    if (issue)
+        codes.add("check-command");
+    if (workflows.some((workflow) => workflow.queue === true) ||
+        (issue && options.queueSeconds !== undefined)) {
+        codes.add("next-command");
+        codes.add("queue-interval");
+    }
+    if (workflows.some((workflow) => hasTicketField(workflow.input)) ||
+        bundled.some((name) => ["develop-ticket", "develop-issue"].includes(name)))
+        codes.add("ticket-command");
+    if (bundled.includes("develop-prd"))
+        codes.add("private-texts");
+    return [...codes];
+}

package/dist/src/execution-pin.d.ts

@@ -1,4 +1,13 @@
 import type { AdmissionResult, ExecutionManifest } from "./workflow-admission.ts";
+import { type CommandWaits } from "./workflow-declaration.ts";
+export declare function executionCapabilities(manifest: ExecutionManifest): string;
 export declare function pinnedIdentity(manifest: ExecutionManifest): string;
 export declare function resumePinned(pinned: ExecutionManifest, available: ExecutionManifest): AdmissionResult;
 export declare function readExecutionManifest(value: unknown): ExecutionManifest;
+export declare function declaredManifest(manifest: ExecutionManifest, declaration: {
+    readonly handoffs?: readonly string[];
+    readonly commands?: readonly string[];
+    readonly commandWaits?: CommandWaits;
+    readonly bundleDigest?: string | undefined;
+    readonly queue?: boolean;
+}): ExecutionManifest;

package/dist/src/execution-pin.js

@@ -1,8 +1,21 @@
+import { isCommandWaits, isWorkflowNames, } from "./workflow-declaration.js";
 const canonical = {
+    queue: (manifest) => JSON.stringify(manifest.queue === true),
     name: (manifest) => JSON.stringify(manifest.name),
     workflowId: (manifest) => JSON.stringify(manifest.workflowId),
     steps: (manifest) => JSON.stringify([...manifest.steps].sort()),
     capabilities: (manifest) => JSON.stringify([...manifest.capabilities].sort()),
+    handoffs: (manifest) => JSON.stringify([...(manifest.handoffs ?? [])].sort()),
+    commands: (manifest) => JSON.stringify([...(manifest.commands ?? [])].sort()),
+    commandWaits: (manifest) => JSON.stringify(Object.entries(manifest.commandWaits ?? {})
+        .sort(([first], [second]) => first < second ? -1 : Number(first > second))
+        .map(([name, wait]) => [
+        name,
+        wait.command,
+        wait.maximumWaitSeconds,
+        wait.pollEverySeconds,
+    ])),
+    bundleDigest: (manifest) => JSON.stringify(manifest.bundleDigest),
     artifacts: (manifest) => JSON.stringify(Object.keys(manifest.artifacts)
         .sort()
         .map((name) => [name, manifest.artifacts[name]])),
@@ -20,11 +33,33 @@ const fields = [
     "resources",
     "toolchain",
 ];
+export function executionCapabilities(manifest) {
+    const handoff = manifest.handoffs?.length ? ["handoff"] : [];
+    return JSON.stringify([...new Set([...manifest.capabilities, ...handoff])].sort());
+}
 export function pinnedIdentity(manifest) {
-    return JSON.stringify(fields.map((field) => canonical[field](manifest)));
+    const identity = fields.map((field) => canonical[field](manifest));
+    if (manifest.handoffs?.length)
+        identity.push(canonical.handoffs(manifest));
+    if (manifest.commands?.length)
+        identity.push(JSON.stringify(["commands", canonical.commands(manifest)]));
+    if (Object.keys(manifest.commandWaits ?? {}).length > 0)
+        identity.push(JSON.stringify(["commandWaits", canonical.commandWaits(manifest)]));
+    if (manifest.bundleDigest !== undefined)
+        identity.push(canonical.bundleDigest(manifest));
+    if (manifest.queue === true)
+        identity.push(JSON.stringify(["queue", true]));
+    return JSON.stringify(identity);
 }
 export function resumePinned(pinned, available) {
-    const changed = fields.find((field) => canonical[field](pinned) !== canonical[field](available));
+    const changed = [
+        ...fields,
+        "handoffs",
+        "commands",
+        "commandWaits",
+        "bundleDigest",
+        "queue",
+    ].find((field) => canonical[field](pinned) !== canonical[field](available));
     if (changed !== undefined)
         return {
             kind: "rejected",
@@ -36,11 +71,24 @@ export function resumePinned(pinned, available) {
 export function readExecutionManifest(value) {
     const fields = record(value);
     const toolchain = record(fields["toolchain"]);
+    const handoffs = fields["handoffs"];
+    const commands = fields["commands"];
+    if (Object.hasOwn(fields, "handoffs") && !isWorkflowNames(handoffs))
+        throw new Error("invalid-handoffs");
+    if (Object.hasOwn(fields, "commands") && !isWorkflowNames(commands))
+        throw new Error("invalid-commands");
     return {
         name: text(fields["name"]),
         workflowId: text(fields["workflowId"]),
         steps: texts(fields["steps"]),
         capabilities: texts(fields["capabilities"]),
+        ...queueMetadata(fields),
+        ...(isWorkflowNames(handoffs) ? { handoffs: [...handoffs] } : {}),
+        ...(isWorkflowNames(commands) ? { commands: [...commands] } : {}),
+        ...readCommandWaits(fields),
+        ...(Object.hasOwn(fields, "bundleDigest")
+            ? { bundleDigest: text(fields["bundleDigest"]) }
+            : {}),
         artifacts: textRecord(fields["artifacts"]),
         resources: textRecord(fields["resources"]),
         toolchain: {
@@ -52,6 +100,37 @@ export function readExecutionManifest(value) {
         },
     };
 }
+function readCommandWaits(fields) {
+    if (!Object.hasOwn(fields, "commandWaits"))
+        return {};
+    const commandWaits = fields["commandWaits"];
+    if (!isCommandWaits(commandWaits, {
+        capabilities: texts(fields["capabilities"]),
+        commands: texts(fields["commands"]),
+    }))
+        throw new Error("invalid-command-waits");
+    return {
+        commandWaits: Object.fromEntries(Object.entries(commandWaits).map(([name, wait]) => [name, { ...wait }])),
+    };
+}
+export function declaredManifest(manifest, declaration) {
+    return readExecutionManifest({
+        ...manifest,
+        ...(declaration.queue === undefined ? {} : { queue: declaration.queue }),
+        ...(declaration.commands === undefined
+            ? {}
+            : { commands: declaration.commands }),
+        ...(declaration.commandWaits === undefined
+            ? {}
+            : { commandWaits: declaration.commandWaits }),
+        ...(declaration.handoffs === undefined
+            ? {}
+            : { handoffs: declaration.handoffs }),
+        ...(declaration.bundleDigest === undefined
+            ? {}
+            : { bundleDigest: declaration.bundleDigest }),
+    });
+}
 function record(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return {};
@@ -66,3 +145,8 @@ function texts(value) {
 function textRecord(value) {
     return Object.fromEntries(Object.entries(record(value)).map(([key, item]) => [key, text(item)]));
 }
+function queueMetadata(fields) {
+    if (Object.hasOwn(fields, "queue") && typeof fields["queue"] !== "boolean")
+        throw new Error("invalid-queue");
+    return fields["queue"] === true ? { queue: true } : {};
+}

package/dist/src/grok-result.d.ts

@@ -0,0 +1,12 @@
+import { type WorkerUsage } from "./worker-usage.ts";
+export declare function grokResultFields(value: unknown): {
+    readonly usage: WorkerUsage;
+    readonly failed: boolean;
+    readonly pricingModel: string | null;
+    readonly costUsd: number | null;
+    readonly model?: string;
+};
+export declare function grokUsageWarnings(): {
+    readonly write: (chunk: string) => void;
+    readonly incomplete: () => boolean;
+};

package/dist/src/grok-result.js

@@ -0,0 +1,61 @@
+import { record } from "./protocol.js";
+import { tokenCount, usageOf } from "./worker-usage.js";
+function grokUsage(value) {
+    const fields = record(value) ?? {};
+    const input = tokenCount(fields["input_tokens"]);
+    const creation = tokenCount(fields["cache_creation_input_tokens"]);
+    const read = tokenCount(fields["cache_read_input_tokens"]);
+    const output = tokenCount(fields["output_tokens"]);
+    if (input === null || creation === null || read === null || output === null)
+        return usageOf(null);
+    if (input + creation + read + output === 0)
+        return usageOf(null);
+    return {
+        input_tokens: tokenCount(input + creation),
+        cache_read_input_tokens: read,
+        output_tokens: output,
+    };
+}
+function attributedModel(result) {
+    const entries = Object.entries(record(result["modelUsage"]) ?? {});
+    const [entry] = entries;
+    if (entries.length !== 1 || entry === undefined)
+        return null;
+    const [model, row] = entry;
+    const counts = record(row) ?? {};
+    const aggregate = record(result["usage"]) ?? {};
+    const fields = [
+        ["input_tokens", "inputTokens"],
+        ["cache_creation_input_tokens", "cacheCreationInputTokens"],
+        ["cache_read_input_tokens", "cacheReadInputTokens"],
+        ["output_tokens", "outputTokens"],
+    ];
+    return fields.every(([total, key]) => tokenCount(aggregate[total]) !== null && aggregate[total] === counts[key])
+        ? model
+        : null;
+}
+export function grokResultFields(value) {
+    const fields = record(value) ?? {};
+    const usage = grokUsage(fields["usage"]);
+    const model = attributedModel(fields);
+    return {
+        usage,
+        failed: fields["subtype"] !== "success" || fields["is_error"] !== false,
+        pricingModel: model,
+        costUsd: null,
+        ...(model === null ? {} : { model }),
+    };
+}
+export function grokUsageWarnings() {
+    let tail = "";
+    let incomplete = false;
+    return {
+        write: (chunk) => {
+            const text = tail + chunk;
+            incomplete ||=
+                /streaming-messages-json: (usage is incomplete|no aggregate usage ledger at turn end)/.test(text);
+            tail = text.slice(-128);
+        },
+        incomplete: () => incomplete,
+    };
+}

package/dist/src/harness-defaults.d.ts

@@ -0,0 +1,35 @@
+export declare const defaultCommand: string[];
+export declare const defaultCodexCommand: string[];
+export declare const defaultGeminiCommand: string[];
+export declare const defaultCursorCommand: string[];
+export declare const defaultOpencodeCommand: string[];
+export declare const defaultGrokCommand: string[];
+export type NativeHarness = "claude" | "codex" | "gemini" | "grok" | "opencode" | "cursor-agent";
+export interface HarnessSettings {
+    readonly worker?: string;
+    readonly command?: readonly string[];
+    readonly workerCommands?: Readonly<Partial<Record<NativeHarness, readonly string[]>>>;
+    readonly harness?: {
+        readonly name?: string;
+        readonly kind?: "file" | "shell";
+        readonly path?: string;
+        readonly command?: readonly string[];
+        readonly turn?: readonly string[];
+        readonly output?: "text";
+    };
+    readonly shell?: string;
+}
+export declare function isTurnCommand(value: unknown): value is readonly string[];
+export declare function harnessDefaults(value: unknown): {
+    readonly command: readonly string[];
+    readonly variable?: string;
+};
+export declare function turnHarness(settings: HarnessSettings, profile?: {
+    readonly harness?: string;
+}): {
+    readonly worker: string;
+    readonly command: readonly string[];
+    readonly shell?: string;
+    readonly output?: "text";
+};
+export declare function nativeHarness(name: string): name is NativeHarness;