cloving 1.2.0 → 1.4.0

package/dist/src/testing.js

@@ -0,0 +1,211 @@
+import { spawn } from "node:child_process";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { workflowTestLoader } from "../tools/workflow-test-loader.js";
+import { authorizeEffect } from "./effect-authorization.js";
+import { scenarioResult, } from "./testing-requests.js";
+import { stepBridgeKey, } from "./step-bridge.js";
+export function fakeStepBridge(scenario) {
+    const { bridge, requests, budget } = scenarioBridge(scenario);
+    const key = Symbol.for(stepBridgeKey);
+    const sleepKey = Symbol.for("WORKFLOW_SLEEP");
+    const previous = Object.getOwnPropertyDescriptor(globalThis, key);
+    const previousSleep = Object.getOwnPropertyDescriptor(globalThis, sleepKey);
+    if (Reflect.get(globalThis, key) !== undefined ||
+        Reflect.get(globalThis, sleepKey) !== undefined)
+        throw new Error("workflow-testing-host-active");
+    if (previous?.configurable === false || previousSleep?.configurable === false)
+        throw new Error("workflow-testing-host-locked");
+    Object.defineProperty(globalThis, key, { configurable: true, value: bridge });
+    Object.defineProperty(globalThis, sleepKey, {
+        configurable: true,
+        value: (milliseconds) => {
+            requests.push([
+                "sleep",
+                milliseconds instanceof Date
+                    ? { until: milliseconds.toISOString() }
+                    : { seconds: milliseconds / 1000 },
+            ]);
+            return Promise.resolve();
+        },
+    });
+    return {
+        requests,
+        get spent() {
+            return budget.spent;
+        },
+        [Symbol.dispose]() {
+            if (previous === undefined)
+                Reflect.deleteProperty(globalThis, key);
+            else
+                Object.defineProperty(globalThis, key, previous);
+            if (previousSleep === undefined)
+                Reflect.deleteProperty(globalThis, sleepKey);
+            else
+                Object.defineProperty(globalThis, sleepKey, previousSleep);
+        },
+    };
+}
+function scenarioBridge(scenario) {
+    const requests = [];
+    const waits = [...(scenario.waits ?? [])];
+    const decisions = [...(scenario.decisions ?? [])];
+    const budget = { spent: 0 };
+    const bridge = {
+        ...scenarioEffects(scenario, { requests, budget }),
+        ...scenarioCommandWaits(scenario, requests),
+        gate: (request) => {
+            requests.push(["gate", request]);
+            return Promise.resolve(scenario.gate ?? {
+                kind: "unavailable",
+                reason: "no-scenario-result",
+            });
+        },
+        waitForDecision: (request) => {
+            requests.push(["waitForDecision", request]);
+            const decision = decisions.shift();
+            if (decision === undefined)
+                return Promise.reject(new Error("no-scenario-result"));
+            return Promise.resolve(decision);
+        },
+        waitForRun: (request) => {
+            requests.push(["waitForRun", request]);
+            return Promise.resolve(waits.shift() ?? {
+                kind: "unavailable",
+                reason: "no-scenario-result",
+                promotionId: null,
+            });
+        },
+    };
+    return { bridge, requests, budget };
+}
+function scenarioCommandWaits(scenario, requests) {
+    const waits = new Map(Object.entries(scenario.commandWaits ?? {}).map(([name, values]) => [
+        name,
+        [...values],
+    ]));
+    return {
+        openCommandWait: (request) => {
+            requests.push(["waitForCommand", request]);
+            if (!waits.get(request.name)?.length)
+                return Promise.reject(new Error("no-scenario-result"));
+            return Promise.resolve({
+                kind: "pending",
+                deadline: 0,
+                nextCheckAt: 0,
+            });
+        },
+        checkCommandWait: (request) => {
+            const result = waits.get(request.name)?.shift();
+            if (result === undefined)
+                return Promise.reject(new Error("no-scenario-result"));
+            return Promise.resolve(result);
+        },
+    };
+}
+function scenarioEffects(scenario, state) {
+    const { requests, budget } = state;
+    const effects = new Map(Object.entries(scenario.effects ?? {}).map(([key, values]) => [
+        key,
+        [...values],
+    ]));
+    return {
+        effect: (request) => {
+            requests.push(["effect", request]);
+            const refusal = spend(scenario, { budget, request });
+            if (refusal !== undefined)
+                return Promise.resolve(refusal);
+            const result = scenario.effects === undefined
+                ? scenario.turn
+                : effects.get(request.capability + " " + request.method)?.shift();
+            return Promise.resolve(result ?? { kind: "unavailable", reason: "no-scenario-result" });
+        },
+        handoff: (request) => {
+            requests.push(["handoff", request]);
+            const refusal = spend(scenario, {
+                budget,
+                request: { capability: "handoff", units: 1 },
+            });
+            if (refusal !== undefined)
+                return Promise.resolve(refusal);
+            return Promise.resolve(effects.get("handoff")?.shift() ?? {
+                kind: "completed",
+                operationId: "handoff",
+                receipt: null,
+                result: "target-run",
+            });
+        },
+    };
+}
+function spend(scenario, effect) {
+    const { budget, request } = effect;
+    if (scenario.effectLimit === undefined)
+        return undefined;
+    const allowed = authorizeEffect({ capabilities: ["claude", "github", "command", "handoff"] }, {
+        budget: { limit: scenario.effectLimit, spent: budget.spent },
+        request,
+    });
+    if (allowed.kind === "rejected")
+        return { kind: "refused", reason: allowed.reason };
+    budget.spent = allowed.spent;
+    return undefined;
+}
+function scenarioScript(scenario) {
+    const workflow = scenario.workflow.startsWith("file:")
+        ? scenario.workflow
+        : pathToFileURL(resolve(scenario.workflow)).href;
+    return `import { writeFile } from "node:fs/promises";
+import { fakeStepBridge } from ${JSON.stringify(import.meta.url)};
+import * as workflows from ${JSON.stringify(workflow)};
+const given = ${JSON.stringify(scenario)};
+const workflow = workflows[given.exportName];
+if (typeof workflow !== "function") throw new Error("workflow-test-export-missing");
+using bridge = fakeStepBridge(given);
+const outcome = await workflow(given.input);
+await writeFile(process.argv[2], JSON.stringify({ outcome, requests: bridge.requests,
+  ...(given.effectLimit === undefined ? {} : { spent: bridge.spent }) }));`;
+}
+export async function runScenario(scenario) {
+    const temporary = await mkdtemp(join(tmpdir(), "cloving-scenario-"));
+    try {
+        const script = join(temporary, "scenario.mjs");
+        const resultFile = join(temporary, "result.json");
+        await writeFile(script, scenarioScript(scenario));
+        await executeScenario(script, resultFile);
+        const value = JSON.parse(await readFile(resultFile, "utf8"));
+        if (!scenarioResult(value))
+            throw new Error("invalid-workflow-scenario-result");
+        return value;
+    }
+    finally {
+        await rm(temporary, { recursive: true, force: true });
+    }
+}
+function executeScenario(script, resultFile) {
+    return new Promise((settle, reject) => {
+        const child = spawn(process.execPath, [
+            "--experimental-strip-types",
+            "--import",
+            workflowTestLoader(),
+            script,
+            resultFile,
+        ], {
+            env: { ...process.env, NODE_TEST_CONTEXT: undefined },
+            stdio: ["ignore", "ignore", "pipe"],
+        });
+        let diagnostics = "";
+        child.stderr.setEncoding("utf8");
+        child.stderr.on("data", (text) => {
+            diagnostics = (diagnostics + text).slice(-65536);
+        });
+        child.once("error", reject);
+        child.once("close", (code, signal) => {
+            if (code === 0)
+                settle();
+            else
+                reject(new Error(`workflow-scenario-failed: ${String(code ?? signal)}\n${diagnostics}`));
+        });
+    });
+}

package/dist/src/ticket-status-stream.d.ts

@@ -0,0 +1,9 @@
+import { type TicketStatus } from "./ticket-status.ts";
+export interface StreamedTicketStatus {
+    readonly ticketStatus: TicketStatus;
+    readonly ticketStatusTooLarge?: true;
+}
+export declare function ticketStatusStream(limit: number): {
+    write: (chunk: string) => void;
+    result: () => StreamedTicketStatus;
+};

package/dist/src/ticket-status-stream.js

@@ -0,0 +1,94 @@
+import { ticketStatus } from "./ticket-status.js";
+function emptyLine() {
+    return {
+        text: "",
+        length: 0,
+        contentLength: 0,
+        breaks: 0,
+        trailingCarriage: false,
+    };
+}
+function remainingLine(stream, line) {
+    if (line.length <= stream.limit && line.text === "Remaining:") {
+        stream.remaining = [];
+        stream.characters = 0;
+        stream.valid = true;
+        return;
+    }
+    if (!stream.valid)
+        return;
+    if (line.breaks > 0 || !/^- \S.*$/.test(line.text)) {
+        stream.valid = false;
+        return;
+    }
+    stream.characters = Math.min(stream.limit + 1, stream.characters + line.length + 1);
+    if (stream.characters <= stream.limit)
+        stream.remaining.push(line.text.slice(2));
+}
+function receivedLine(stream) {
+    const line = stream.line;
+    stream.line = emptyLine();
+    if (line.contentLength === 0)
+        return;
+    if (line.trailingCarriage)
+        line.breaks--;
+    if (line.length <= stream.limit + 1 && line.trailingCarriage) {
+        line.text = line.text.slice(0, -1);
+        line.length--;
+    }
+    if (stream.last !== undefined)
+        remainingLine(stream, stream.last);
+    if (/^Ticket status:/i.test(line.text))
+        stream.statuses = Math.min(2, stream.statuses + 1);
+    stream.last = line;
+}
+function writeStatus(stream, chunk) {
+    const parts = chunk.split("\n");
+    for (const [index, part] of parts.entries()) {
+        const { line, limit } = stream;
+        const content = part.trimEnd();
+        line.breaks = Math.min(2, line.breaks + (part.match(/[\r\u2028\u2029]/g)?.length ?? 0));
+        if (part !== "")
+            line.trailingCarriage = part.endsWith("\r");
+        if (content !== "")
+            line.contentLength = Math.min(limit + 1, line.length + content.length);
+        line.text = (line.text + part).slice(0, limit + 1);
+        line.length = Math.min(limit + 2, line.length + part.length);
+        if (index < parts.length - 1)
+            receivedLine(stream);
+    }
+}
+function statusResult(stream) {
+    receivedLine(stream);
+    const last = stream.last;
+    if (stream.statuses !== 1 || last === undefined)
+        return { ticketStatus: ticketStatus("") };
+    const status = last.contentLength > stream.limit ? "" : last.text.trimEnd();
+    if (status !== "Ticket status: partial" || !stream.valid)
+        return { ticketStatus: ticketStatus(status) };
+    if (stream.characters > stream.limit)
+        return {
+            ticketStatus: ticketStatus(status),
+            ticketStatusTooLarge: true,
+        };
+    return {
+        ticketStatus: ticketStatus(`Remaining:\n${stream.remaining.map((item) => `- ${item}`).join("\n")}\n${status}`),
+    };
+}
+export function ticketStatusStream(limit) {
+    const stream = {
+        limit,
+        line: emptyLine(),
+        last: undefined,
+        statuses: 0,
+        remaining: [],
+        characters: 0,
+        valid: false,
+    };
+    return {
+        write: (chunk) => {
+            writeStatus(stream, chunk);
+        },
+        result: () => statusResult(stream),
+    };
+}

package/dist/src/token-prices.d.ts

@@ -1,4 +1,5 @@
-import { type WorkerUsage } from "./worker-usage.ts";
+import { type WorkerUsage, type WorkerModelUsage } from "./worker-usage.ts";
+import type { NativeHarness } from "./harness-defaults.ts";
 export interface TokenPrice {
     readonly input: number;
     readonly cachedInput: number;
@@ -15,7 +16,14 @@ export declare function parseFallbackModels(value: string | undefined): readonly
 export declare function priceForModel(prices: TokenPrices, model: string | null): TokenPrice | undefined;
 export declare function commandModel(command: readonly string[]): string | null;
 export declare function replaceCommandModel(command: readonly string[], model: string): readonly string[];
-export declare function estimatedCostUsd(usage: WorkerUsage, pricing: {
-    readonly worker: "claude" | "codex";
+interface SinglePricing {
+    readonly worker: NativeHarness;
     readonly price: TokenPrice | undefined;
-}): number | null;
+}
+interface ModelPricing {
+    readonly worker: "gemini";
+    readonly models: readonly WorkerModelUsage[];
+    readonly prices: TokenPrices;
+}
+export declare function estimatedCostUsd(usage: WorkerUsage, pricing: SinglePricing | ModelPricing): number | null;
+export {};

package/dist/src/token-prices.js

@@ -1,4 +1,4 @@
-import { priceOf, usageOf } from "./worker-usage.js";
+import { priceOf, sumPrices, usageOf, } from "./worker-usage.js";
 import { record } from "./protocol.js";
 export const builtInPriceTable = {
     date: "2026-10-18",
@@ -90,16 +90,29 @@ export function replaceCommandModel(command, model) {
     });
 }
 export function estimatedCostUsd(usage, pricing) {
+    return "models" in pricing
+        ? modelCostUsd(pricing)
+        : singleCostUsd(usage, pricing);
+}
+function modelCostUsd(pricing) {
+    return sumPrices(pricing.models.map(({ model, usage: counts }) => singleCostUsd(counts, {
+        worker: "gemini",
+        price: priceForModel(pricing.prices, model),
+    })));
+}
+function singleCostUsd(usage, pricing) {
     const { worker, price } = pricing;
     const counts = usageOf(usage);
     const cached = counts.cache_read_input_tokens;
     const output = counts.output_tokens;
     if (price === undefined ||
+        (worker === "cursor-agent" && counts.cache_creation_input_tokens !== 0) ||
         counts.input_tokens === null ||
         cached === null ||
         output === null)
         return null;
-    const input = counts.input_tokens - (worker === "codex" ? cached : 0);
+    const input = counts.input_tokens -
+        (worker === "codex" || worker === "gemini" ? cached : 0);
     if (input < 0)
         return null;
     return priceOf((input / 1_000_000) * price.input +

package/dist/src/turn-profile.d.ts

@@ -1,4 +1,5 @@
 export interface TurnProfile {
+    readonly harness?: string;
     readonly env?: Readonly<Record<string, string>>;
     readonly allowedTools?: readonly string[];
     readonly model?: string;

package/dist/src/turn-profile.js

@@ -1,4 +1,5 @@
 const fields = [
+    "harness",
     "env",
     "allowedTools",
     "model",
@@ -29,6 +30,8 @@ function environment(value) {
             text(item)));
 }
 function validField(name, value) {
+    if (name === "harness")
+        return typeof value === "string" && /^[a-z][a-z0-9-]{0,63}$/.test(value);
     if (name === "env")
         return environment(value);
     if (name === "allowedTools" || name === "workflows")
@@ -71,7 +74,11 @@ function retained(argumentsList, values) {
     for (let index = 0; index < argumentsList.length;) {
         const argument = argumentsList[index] ?? "";
         const name = argument.split("=")[0] ?? "";
-        const flag = name === "--allowed-tools" ? "--allowedTools" : name;
+        const aliases = {
+            "--allowed-tools": "--allowedTools",
+            "-m": "--model",
+        };
+        const flag = aliases[name] ?? name;
         if (!values.has(flag)) {
             kept.push(argument);
             index += 1;

package/dist/src/worker-usage.d.ts

@@ -1,9 +1,14 @@
+export type RetryKind = "capacity" | "network";
 export interface WorkerUsage {
+    readonly cache_creation_input_tokens?: number | null;
     readonly input_tokens: number | null;
     readonly cache_read_input_tokens: number | null;
     readonly output_tokens: number | null;
 }
 export interface WorkerTurnUsage {
+    readonly model?: string;
+    readonly summary?: string;
+    readonly harness?: string;
     readonly attempts?: readonly WorkerAttemptUsage[];
     readonly estimatedCostUsd: number | null;
     readonly operationId: string;
@@ -11,12 +16,20 @@ export interface WorkerTurnUsage {
     readonly costUsd: number | null;
 }
 export interface WorkerAttemptUsage {
+    readonly resumedAfter?: "daemon-restart";
+    readonly models?: readonly WorkerModelUsage[];
+    readonly retryKind?: RetryKind | null;
     readonly attempt: number;
     readonly model: string | null;
     readonly usage: WorkerUsage;
     readonly costUsd: number | null;
     readonly estimatedCostUsd: number | null;
 }
+export interface WorkerModelUsage {
+    readonly model: string;
+    readonly usage: WorkerUsage;
+}
+export declare function modelUsageOf(value: unknown): readonly WorkerModelUsage[] | undefined;
 export interface WorkerTotals {
     readonly estimatedCostUsd: number | null;
     readonly workerTurns: readonly WorkerTurnUsage[];
@@ -29,3 +42,7 @@ export declare function usageOf(value: unknown): WorkerUsage;
 export declare function sumUsage(values: readonly WorkerUsage[]): WorkerUsage;
 export declare function sumPrices(values: readonly (number | null)[]): number | null;
 export declare function workerTotals(workerTurns: readonly WorkerTurnUsage[]): WorkerTotals;
+export declare function attemptsOf(value: unknown): readonly WorkerAttemptUsage[] | undefined;
+export declare function attemptFields(value: unknown): {
+    readonly attempts?: readonly WorkerAttemptUsage[];
+};

package/dist/src/worker-usage.js

@@ -1,3 +1,15 @@
+export function modelUsageOf(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    return value.flatMap((entry) => {
+        if (typeof entry !== "object" || entry === null)
+            return [];
+        const model = Reflect.get(entry, "model");
+        if (typeof model !== "string")
+            return [];
+        return [{ model, usage: usageOf(Reflect.get(entry, "usage")) }];
+    });
+}
 export function priceOf(value) {
     return typeof value === "number" && Number.isFinite(value) && value >= 0
         ? value
@@ -11,6 +23,11 @@ export function tokenCount(value) {
 export function usageOf(value) {
     const fields = typeof value === "object" && value !== null ? value : {};
     return {
+        ...(Object.hasOwn(fields, "cache_creation_input_tokens")
+            ? {
+                cache_creation_input_tokens: tokenCount(Reflect.get(fields, "cache_creation_input_tokens")),
+            }
+            : {}),
         input_tokens: tokenCount(Reflect.get(fields, "input_tokens")),
         cache_read_input_tokens: tokenCount(Reflect.get(fields, "cache_read_input_tokens")),
         output_tokens: tokenCount(Reflect.get(fields, "output_tokens")),
@@ -23,6 +40,11 @@ function total(values) {
 }
 export function sumUsage(values) {
     return {
+        ...(values.some((value) => Object.hasOwn(value, "cache_creation_input_tokens"))
+            ? {
+                cache_creation_input_tokens: total(values.map((value) => value.cache_creation_input_tokens ?? null)),
+            }
+            : {}),
         input_tokens: total(values.map((value) => value.input_tokens)),
         cache_read_input_tokens: total(values.map((value) => value.cache_read_input_tokens)),
         output_tokens: total(values.map((value) => value.output_tokens)),
@@ -42,3 +64,41 @@ export function workerTotals(workerTurns) {
         estimatedCostUsd: sumPrices(workerTurns.map((turn) => turn.estimatedCostUsd)),
     };
 }
+function retryKindField(value) {
+    return value === null || value === "capacity" || value === "network"
+        ? { retryKind: value }
+        : {};
+}
+export function attemptsOf(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    return value.flatMap((entry) => {
+        const fields = typeof entry === "object" && entry !== null ? entry : {};
+        const field = (name) => Reflect.get(fields, name);
+        const attempt = tokenCount(field("attempt"));
+        const model = field("model");
+        const models = modelUsageOf(field("models"));
+        if (attempt === null ||
+            attempt === 0 ||
+            (model !== null && typeof model !== "string"))
+            return [];
+        return [
+            {
+                ...retryKindField(field("retryKind")),
+                ...(field("resumedAfter") === "daemon-restart"
+                    ? { resumedAfter: "daemon-restart" }
+                    : {}),
+                attempt,
+                model,
+                ...(models === undefined ? {} : { models }),
+                usage: usageOf(field("usage")),
+                costUsd: priceOf(field("costUsd")),
+                estimatedCostUsd: priceOf(field("estimatedCostUsd")),
+            },
+        ];
+    });
+}
+export function attemptFields(value) {
+    const attempts = attemptsOf(value);
+    return attempts === undefined ? {} : { attempts };
+}

package/dist/src/workflow-admission.d.ts

@@ -1,3 +1,4 @@
+import type { CommandWaits } from "./workflow-declaration.ts";
 export interface ToolchainIdentity {
     readonly sdk: string;
     readonly world: string;
@@ -23,11 +24,15 @@ export interface AdmissionPolicy {
     readonly capabilities: readonly string[];
 }
 export interface ExecutionManifest {
+    readonly queue?: boolean;
     readonly name: string;
     readonly workflowId: string;
     readonly steps: readonly string[];
     readonly capabilities: readonly string[];
     readonly handoffs?: readonly string[];
+    readonly commands?: readonly string[];
+    readonly commandWaits?: CommandWaits;
+    readonly bundleDigest?: string;
     readonly artifacts: Readonly<Record<string, string>>;
     readonly resources: Readonly<Record<string, string>>;
     readonly toolchain: ToolchainIdentity;

package/dist/src/workflow-candidate.d.ts

@@ -1,4 +1,4 @@
-import { type WorkflowDeclaration } from "./workflow-declaration.ts";
+import { type WorkflowQueueCode, type WorkflowDeclaration } from "./workflow-declaration.ts";
 export interface CandidateDeclaration {
     readonly workflow: WorkflowDeclaration;
     readonly methods: Readonly<Record<string, readonly string[]>>;
@@ -6,12 +6,15 @@ export interface CandidateDeclaration {
 export interface CandidateImport {
     readonly module: string;
     readonly names: readonly string[];
+    readonly source?: string;
 }
 export interface CandidateEffect {
     readonly capability: string | null;
     readonly method: string | null;
 }
 export interface CandidateAnalysis {
+    readonly commandWaits?: readonly (string | null)[];
+    readonly localSources?: readonly string[];
     readonly imports: readonly CandidateImport[];
     readonly effects: readonly CandidateEffect[];
     readonly directEffects: readonly string[];
@@ -20,10 +23,13 @@ export interface CandidateAnalysis {
     readonly knownUnitTotal: number;
 }
 export type InstalledWorkflowExports = Readonly<Record<string, readonly string[]>>;
-export type WorkflowCandidateCode = "invalid-declaration" | "forbidden-import" | "missing-export" | "unsupported-source" | "dynamic-effect" | "undeclared-effect" | "effect-limit" | "direct-effect";
+export type WorkflowCandidateCode = WorkflowQueueCode | "invalid-declaration" | "forbidden-import" | "missing-export" | "unsupported-source" | "dynamic-effect" | "undeclared-effect" | "effect-limit" | "direct-effect";
 export interface WorkflowCandidateInput {
     readonly declaration: unknown;
     readonly analysis: CandidateAnalysis;
     readonly installedExports: InstalledWorkflowExports;
 }
+export declare function workflowHelperPath(source: string, imported: string): string | undefined;
+export declare function isCandidateDeclaration(value: unknown): value is CandidateDeclaration;
 export declare function checkWorkflowCandidate(input: WorkflowCandidateInput): readonly WorkflowCandidateCode[];
+export declare function candidateDeclarationRefusals(value: unknown): readonly WorkflowCandidateCode[];