cloving 0.3.20 → 1.1.0

package/dist/src/storage/statements.d.ts

@@ -0,0 +1,9 @@
+export interface Statement {
+    readonly sql: string;
+    readonly parameters: readonly unknown[];
+}
+export declare function upsert(target: {
+    readonly table: string;
+    readonly names: readonly string[];
+    readonly key: number;
+}): string;

package/dist/src/storage/statements.js

@@ -0,0 +1,8 @@
+export function upsert(target) {
+    const { table, names, key } = target;
+    const updates = names
+        .slice(key)
+        .map((name) => `${name} = excluded.${name}`)
+        .join(", ");
+    return `INSERT INTO ${table} (${names.join(", ")}) VALUES (${names.map(() => "?").join(", ")}) ON CONFLICT (${names.slice(0, key).join(", ")}) DO UPDATE SET ${updates}`;
+}

package/dist/src/submission.d.ts

@@ -0,0 +1,42 @@
+import { type Fields } from "./protocol.ts";
+export type SubmissionField = {
+    readonly type: "string";
+    readonly optional?: boolean;
+} | {
+    readonly type: "boolean";
+    readonly optional?: boolean;
+} | {
+    readonly type: "integer";
+    readonly optional?: boolean;
+    readonly minimum?: number;
+    readonly maximum?: number;
+};
+export interface SubmissionContract {
+    readonly maximumBytes: number;
+    readonly fields: Readonly<Record<string, "string" | SubmissionField>>;
+}
+export type SubmissionCheck = {
+    readonly kind: "valid";
+    readonly normalized: string;
+    readonly submission: Fields;
+} | {
+    readonly kind: "rejected";
+    readonly code: string;
+    readonly detail: string;
+};
+export interface SubmissionRequest {
+    readonly workflowId: string;
+    readonly submission: unknown;
+    readonly source: unknown;
+}
+export declare function normalizedRequest(workflowId: string, submission: Fields): string;
+export declare function checkSubmission(contract: SubmissionContract, request: SubmissionRequest): SubmissionCheck;
+export type CheckedResolution = {
+    readonly kind: "resolved";
+    readonly input: string;
+} | {
+    readonly kind: "rejected";
+    readonly code: string;
+    readonly detail: string;
+};
+export declare function checkResolution(value: unknown): CheckedResolution | undefined;

package/dist/src/submission.js

@@ -0,0 +1,71 @@
+import { record } from "./protocol.js";
+function rejected(code, detail) {
+    return { kind: "rejected", code, detail };
+}
+function sorted(fields) {
+    return Object.fromEntries(Object.keys(fields)
+        .sort()
+        .map((key) => [key, fields[key]]));
+}
+function invalidField(contract, submission) {
+    const undeclared = Object.keys(submission).find((key) => !Object.hasOwn(contract.fields, key));
+    if (undeclared !== undefined)
+        return undeclared;
+    return Object.entries(contract.fields).find(([key, rule]) => {
+        if (rule !== "string" && rule.optional && !Object.hasOwn(submission, key))
+            return false;
+        return !validValue(rule, submission[key]);
+    })?.[0];
+}
+function validValue(rule, value) {
+    if (rule === "string" || rule.type === "string")
+        return typeof value === "string" && value.trim().length > 0;
+    if (rule.type === "boolean")
+        return typeof value === "boolean";
+    return (typeof value === "number" &&
+        Number.isInteger(value) &&
+        (rule.minimum === undefined || value >= rule.minimum) &&
+        (rule.maximum === undefined || value <= rule.maximum));
+}
+export function normalizedRequest(workflowId, submission) {
+    return JSON.stringify({ submission: sorted(submission), workflowId });
+}
+export function checkSubmission(contract, request) {
+    if (request.source === "prompt" && !Object.hasOwn(contract.fields, "prompt"))
+        return rejected("unsupported-prompt", "The workflow does not accept a prompt. Use --input with its fields.");
+    const submission = record(request.submission);
+    if (submission === undefined)
+        return rejected("invalid-submission", "The submission is not an object.");
+    const bytes = new TextEncoder().encode(JSON.stringify(submission)).length;
+    if (bytes > contract.maximumBytes)
+        return rejected("input-too-large", `The input has ${String(bytes)} bytes. The limit is ${String(contract.maximumBytes)}.`);
+    const field = invalidField(contract, submission);
+    if (field !== undefined)
+        return rejected("invalid-submission", `Field ${field} is not valid.`);
+    return {
+        kind: "valid",
+        normalized: normalizedRequest(request.workflowId, submission),
+        submission,
+    };
+}
+function inputText(input) {
+    try {
+        const text = JSON.stringify(input);
+        return typeof text === "string" ? text : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function checkResolution(value) {
+    const fields = record(value);
+    if (fields === undefined)
+        return undefined;
+    const { kind, code, detail } = fields;
+    if (kind === "rejected" && typeof code === "string" && code.length > 0)
+        return { kind, code, detail: typeof detail === "string" ? detail : code };
+    if (kind !== "resolved")
+        return undefined;
+    const input = inputText(fields["input"]);
+    return input === undefined ? undefined : { kind, input };
+}

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

@@ -0,0 +1,8 @@
+export type TicketStatus = {
+    readonly kind: "complete";
+} | {
+    readonly kind: "partial";
+    readonly remaining: readonly string[];
+};
+export declare function ticketStatus(summary: string, preserved?: unknown): TicketStatus;
+export declare function isTicketStatus(value: unknown): value is "complete" | "partial";

package/dist/src/ticket-status.js

@@ -0,0 +1,45 @@
+function parsedStatus(summary) {
+    const lines = summary.trimEnd().split(/\r?\n/);
+    if (lines.filter((line) => /^Ticket status:/i.test(line)).length !== 1)
+        return undefined;
+    const status = lines.pop();
+    if (status === "Ticket status: complete")
+        return { kind: "complete" };
+    if (status !== "Ticket status: partial")
+        return undefined;
+    const heading = lines.lastIndexOf("Remaining:");
+    if (heading === -1)
+        return undefined;
+    const items = lines.slice(heading + 1);
+    if (items.length === 0 || items.some((line) => !/^- \S.*$/.test(line)))
+        return undefined;
+    return { kind: "partial", remaining: items.map((line) => line.slice(2)) };
+}
+function preservedStatus(value) {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const kind = Reflect.get(value, "kind");
+    if (kind === "complete")
+        return { kind };
+    const remaining = Reflect.get(value, "remaining");
+    if (kind !== "partial" ||
+        !Array.isArray(remaining) ||
+        remaining.length === 0 ||
+        remaining.some((item) => typeof item !== "string" || item.trim() === "" || /[\r\n]/.test(item)))
+        return undefined;
+    return { kind, remaining: remaining.map(String) };
+}
+export function ticketStatus(summary, preserved) {
+    const parsed = preserved === undefined
+        ? parsedStatus(summary)
+        : preservedStatus(preserved);
+    if (parsed !== undefined)
+        return parsed;
+    return {
+        kind: "partial",
+        remaining: ["The worker report has no ticket status line."],
+    };
+}
+export function isTicketStatus(value) {
+    return value === "complete" || value === "partial";
+}

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

@@ -0,0 +1,19 @@
+import { type WorkerUsage } from "./worker-usage.ts";
+export interface TokenPrice {
+    readonly input: number;
+    readonly cachedInput: number;
+    readonly output: number;
+}
+export type TokenPrices = Readonly<Record<string, TokenPrice>>;
+export declare const builtInPriceTable: {
+    readonly date: string;
+    readonly source: string;
+    readonly prices: TokenPrices;
+};
+export declare function parseTokenPrices(value: string | undefined): TokenPrices;
+export declare function priceForModel(prices: TokenPrices, model: string | null): TokenPrice | undefined;
+export declare function commandModel(command: readonly string[]): string | null;
+export declare function estimatedCostUsd(usage: WorkerUsage, pricing: {
+    readonly worker: "claude" | "codex";
+    readonly price: TokenPrice | undefined;
+}): number | null;

package/dist/src/token-prices.js

@@ -0,0 +1,76 @@
+import { priceOf, usageOf } from "./worker-usage.js";
+import { record } from "./protocol.js";
+export const builtInPriceTable = {
+    date: "2026-10-18",
+    source: "https://openai.com/api/pricing/",
+    prices: {
+        "gpt-6.1-sol": { input: 2, cachedInput: 0.1, output: 10 },
+        "gpt-6-astra": { input: 10, cachedInput: 1, output: 50 },
+    },
+};
+function tokenPrice(value) {
+    const fields = record(value);
+    const input = priceOf(fields?.["input"]);
+    const cachedInput = priceOf(fields?.["cachedInput"]);
+    const output = priceOf(fields?.["output"]);
+    if (input === null || cachedInput === null || output === null)
+        throw new Error("Invalid CLOVING_TOKEN_PRICES");
+    return { input, cachedInput, output };
+}
+export function parseTokenPrices(value) {
+    if (value === undefined)
+        return { ...builtInPriceTable.prices };
+    try {
+        const fields = record(JSON.parse(value));
+        if (fields === undefined)
+            throw new Error("Invalid CLOVING_TOKEN_PRICES");
+        return {
+            ...builtInPriceTable.prices,
+            ...Object.fromEntries(Object.entries(fields).map(([model, price]) => [
+                model,
+                tokenPrice(price),
+            ])),
+        };
+    }
+    catch {
+        throw new Error("Invalid CLOVING_TOKEN_PRICES");
+    }
+}
+export function priceForModel(prices, model) {
+    return model !== null && Object.hasOwn(prices, model)
+        ? prices[model]
+        : undefined;
+}
+export function commandModel(command) {
+    let model = null;
+    for (let index = 1; index < command.length; index += 1) {
+        const argument = command[index] ?? "";
+        if (argument === "--")
+            break;
+        if (argument.startsWith("--model="))
+            model = argument.slice(8) || null;
+        if (argument === "--model" || argument === "-m") {
+            const next = command[index + 1];
+            model = next && !next.startsWith("-") ? next : null;
+            index += 1;
+        }
+    }
+    return model;
+}
+export function estimatedCostUsd(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 ||
+        counts.input_tokens === null ||
+        cached === null ||
+        output === null)
+        return null;
+    const input = counts.input_tokens - (worker === "codex" ? cached : 0);
+    if (input < 0)
+        return null;
+    return priceOf((input / 1_000_000) * price.input +
+        (cached / 1_000_000) * price.cachedInput +
+        (output / 1_000_000) * price.output);
+}

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

@@ -0,0 +1,13 @@
+export interface TurnProfile {
+    readonly env?: Readonly<Record<string, string>>;
+    readonly allowedTools?: readonly string[];
+    readonly model?: string;
+    readonly permissionMode?: string;
+    readonly maxBudgetUsd?: number;
+    readonly workflows?: readonly string[];
+}
+export type TurnProfiles = Readonly<Record<string, TurnProfile>>;
+export declare function isProfilesFile(value: unknown): value is {
+    readonly profiles: TurnProfiles;
+};
+export declare function profileCommand(command: readonly string[], profile: TurnProfile): readonly string[];

package/dist/src/turn-profile.js

@@ -0,0 +1,100 @@
+const fields = [
+    "env",
+    "allowedTools",
+    "model",
+    "permissionMode",
+    "maxBudgetUsd",
+    "workflows",
+];
+const reserved = [
+    "GH_TOKEN",
+    "GITHUB_TOKEN",
+    "GH_ENTERPRISE_TOKEN",
+    "GITHUB_ENTERPRISE_TOKEN",
+    "GH_CONFIG_DIR",
+];
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function text(value) {
+    return typeof value === "string" && !value.includes("\0");
+}
+function texts(value) {
+    return Array.isArray(value) && value.every(text);
+}
+function environment(value) {
+    return (record(value) &&
+        Object.entries(value).every(([name, item]) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) &&
+            !reserved.includes(name) &&
+            text(item)));
+}
+function validField(name, value) {
+    if (name === "env")
+        return environment(value);
+    if (name === "allowedTools" || name === "workflows")
+        return texts(value);
+    if (name === "model" || name === "permissionMode")
+        return text(value);
+    return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+function profile(value) {
+    return (record(value) &&
+        Object.entries(value).every(([name, item]) => fields.includes(name) && validField(name, item)));
+}
+export function isProfilesFile(value) {
+    if (!record(value) ||
+        Object.keys(value).length !== 1 ||
+        !record(value["profiles"]))
+        return false;
+    return Object.entries(value["profiles"]).every(([name, item]) => /^[A-Za-z0-9_-]{1,119}$/.test(name) && profile(item));
+}
+function replacements(profile) {
+    const values = new Map();
+    if (profile.allowedTools !== undefined)
+        values.set("--allowedTools", profile.allowedTools.join(","));
+    if (profile.model !== undefined)
+        values.set("--model", profile.model);
+    if (profile.permissionMode !== undefined)
+        values.set("--permission-mode", profile.permissionMode);
+    if (profile.maxBudgetUsd !== undefined)
+        values.set("--max-budget-usd", String(profile.maxBudgetUsd));
+    return values;
+}
+function following(argumentsList, index) {
+    let next = index + 1;
+    while (next < argumentsList.length && !argumentsList[next]?.startsWith("-"))
+        next += 1;
+    return next;
+}
+function retained(argumentsList, values) {
+    const kept = [];
+    for (let index = 0; index < argumentsList.length;) {
+        const argument = argumentsList[index] ?? "";
+        const name = argument.split("=")[0] ?? "";
+        const flag = name === "--allowed-tools" ? "--allowedTools" : name;
+        if (!values.has(flag)) {
+            kept.push(argument);
+            index += 1;
+            continue;
+        }
+        if (argument.includes("=")) {
+            index += 1;
+            continue;
+        }
+        index =
+            flag === "--allowedTools" ? following(argumentsList, index) : index + 2;
+    }
+    return kept;
+}
+export function profileCommand(command, profile) {
+    const [executable = "", ...argumentsList] = command;
+    const separator = argumentsList.indexOf("--");
+    const boundary = separator === -1 ? argumentsList.length : separator;
+    const values = replacements(profile);
+    return [
+        executable,
+        ...retained(argumentsList.slice(0, boundary), values),
+        ...[...values].flat(),
+        ...argumentsList.slice(boundary),
+    ];
+}

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

@@ -0,0 +1,22 @@
+export interface WorkerUsage {
+    readonly input_tokens: number | null;
+    readonly cache_read_input_tokens: number | null;
+    readonly output_tokens: number | null;
+}
+export interface WorkerTurnUsage {
+    readonly estimatedCostUsd: number | null;
+    readonly operationId: string;
+    readonly usage: WorkerUsage;
+    readonly costUsd: number | null;
+}
+export interface WorkerTotals {
+    readonly estimatedCostUsd: number | null;
+    readonly workerTurns: readonly WorkerTurnUsage[];
+    readonly usage: WorkerUsage;
+    readonly claudeCostUsd: number | null;
+}
+export declare function priceOf(value: unknown): number | null;
+export declare function tokenCount(value: unknown): number | null;
+export declare function usageOf(value: unknown): WorkerUsage;
+export declare function sumUsage(values: readonly WorkerUsage[]): WorkerUsage;
+export declare function workerTotals(workerTurns: readonly WorkerTurnUsage[]): WorkerTotals;

package/dist/src/worker-usage.js

@@ -0,0 +1,44 @@
+export function priceOf(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0
+        ? value
+        : null;
+}
+export function tokenCount(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0
+        ? value
+        : null;
+}
+export function usageOf(value) {
+    const fields = typeof value === "object" && value !== null ? value : {};
+    return {
+        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")),
+    };
+}
+function total(values) {
+    if (values.length === 0 || values.includes(null))
+        return null;
+    return tokenCount(values.reduce((sum, value) => sum + (value ?? 0), 0));
+}
+export function sumUsage(values) {
+    return {
+        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)),
+    };
+}
+function sumPrices(values) {
+    const prices = values.map(priceOf);
+    if (prices.length === 0 || prices.includes(null))
+        return null;
+    return priceOf(prices.reduce((sum, price) => sum + (price ?? 0), 0));
+}
+export function workerTotals(workerTurns) {
+    return {
+        workerTurns,
+        usage: sumUsage(workerTurns.map((turn) => turn.usage)),
+        claudeCostUsd: sumPrices(workerTurns.map((turn) => turn.costUsd)),
+        estimatedCostUsd: sumPrices(workerTurns.map((turn) => turn.estimatedCostUsd)),
+    };
+}

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

@@ -0,0 +1,45 @@
+export interface ToolchainIdentity {
+    readonly sdk: string;
+    readonly world: string;
+    readonly builder: string;
+    readonly node: string;
+    readonly dependencies: string;
+}
+export interface WorkflowRegistration {
+    readonly name: string;
+    readonly workflowId: string;
+    readonly steps: readonly string[];
+    readonly capabilities: readonly string[];
+    readonly resources: readonly string[];
+}
+export interface CompiledWorkflow {
+    readonly manifest: unknown;
+    readonly artifacts: Readonly<Record<string, string>>;
+    readonly resources: Readonly<Record<string, string>>;
+    readonly toolchain: ToolchainIdentity;
+}
+export interface AdmissionPolicy {
+    readonly toolchain: ToolchainIdentity;
+    readonly capabilities: readonly string[];
+}
+export interface ExecutionManifest {
+    readonly name: string;
+    readonly workflowId: string;
+    readonly steps: readonly string[];
+    readonly capabilities: readonly string[];
+    readonly artifacts: Readonly<Record<string, string>>;
+    readonly resources: Readonly<Record<string, string>>;
+    readonly toolchain: ToolchainIdentity;
+}
+export type AdmissionResult = {
+    readonly kind: "admitted";
+    readonly manifest: ExecutionManifest;
+} | {
+    readonly kind: "rejected";
+    readonly reason: string;
+    readonly detail: string;
+};
+export declare function admitWorkflow(proposedRegistration: unknown, admission: {
+    readonly compiled: unknown;
+    readonly policy: AdmissionPolicy;
+}): AdmissionResult;

package/dist/src/workflow-admission.js

@@ -0,0 +1,151 @@
+import { resolveResources } from "./workflow-resources.js";
+const versionedStep = /^step\/\/(?!\.)(?:@[^/@]+\/)?[^@]+@[^/@]+\/\/.+$/;
+export function admitWorkflow(proposedRegistration, admission) {
+    const { compiled: proposedCompiled, policy } = admission;
+    const registration = readRegistration(proposedRegistration);
+    if (!registration)
+        return rejected("invalid-registration", "registration");
+    const compiled = record(proposedCompiled) ?? {};
+    const toolchain = readToolchain(compiled["toolchain"]);
+    const rejection = registrationRejection(registration, policy) ??
+        toolchainRejection(toolchain, policy.toolchain) ??
+        manifestRejection(registration, compiled["manifest"]);
+    if (rejection)
+        return rejection;
+    const artifacts = readArtifacts(compiled["artifacts"]);
+    if (!artifacts)
+        return rejected("invalid-artifacts", "artifacts");
+    const resources = resolveResources(registration.resources, compiled["resources"]);
+    if (resources.kind === "inaccessible")
+        return rejected("inaccessible-resource", resources.path);
+    return {
+        kind: "admitted",
+        manifest: Object.freeze({
+            name: registration.name,
+            workflowId: registration.workflowId,
+            steps: Object.freeze([...registration.steps]),
+            capabilities: Object.freeze([...registration.capabilities]),
+            artifacts: Object.freeze(artifacts),
+            resources: Object.freeze(resources.resources),
+            toolchain: Object.freeze(toolchain),
+        }),
+    };
+}
+function readRegistration(value) {
+    const fields = record(value);
+    if (!fields)
+        return null;
+    const { name, workflowId, steps, capabilities, resources } = fields;
+    if (typeof name !== "string" ||
+        typeof workflowId !== "string" ||
+        !textList(steps) ||
+        !textList(capabilities) ||
+        !textList(resources))
+        return null;
+    return { name, workflowId, steps, capabilities, resources };
+}
+function readToolchain(value) {
+    const fields = record(value) ?? {};
+    const textField = (key) => {
+        const field = fields[key];
+        return typeof field === "string" ? field : "";
+    };
+    return {
+        sdk: textField("sdk"),
+        world: textField("world"),
+        builder: textField("builder"),
+        node: textField("node"),
+        dependencies: textField("dependencies"),
+    };
+}
+function readArtifacts(value) {
+    const entries = [];
+    for (const [name, digest] of Object.entries(record(value) ?? {})) {
+        if (typeof digest !== "string" || !/^[0-9a-f]{64}$/.test(digest))
+            return null;
+        entries.push([name, digest]);
+    }
+    return entries.length > 0 ? Object.fromEntries(entries) : null;
+}
+function textList(value) {
+    return (Array.isArray(value) && value.every((item) => typeof item === "string"));
+}
+function registrationRejection(registration, policy) {
+    if (!text(registration.name) ||
+        !text(registration.workflowId) ||
+        !distinctTexts(registration.steps) ||
+        !distinctTexts(registration.capabilities) ||
+        !distinctTexts(registration.resources))
+        return rejected("invalid-registration", "registration");
+    const unversioned = registration.steps.find((step) => !versionedStep.test(step));
+    if (unversioned !== undefined)
+        return rejected("unversioned-step", unversioned);
+    const unsupported = registration.capabilities.find((capability) => !policy.capabilities.includes(capability));
+    if (unsupported !== undefined)
+        return rejected("unsupported-capability", unsupported);
+    return null;
+}
+function toolchainRejection(compiled, accepted) {
+    const keys = ["sdk", "world", "builder", "node", "dependencies"];
+    const changed = keys.find((key) => compiled[key] !== accepted[key]);
+    if (changed !== undefined)
+        return rejected("incompatible-toolchain", changed);
+    return null;
+}
+function manifestRejection(registration, manifest) {
+    const registry = readRegistry(manifest);
+    if (!registry)
+        return rejected("invalid-manifest", "manifest");
+    const identifiers = [...registry.workflows, ...registry.steps];
+    const duplicate = identifiers.find((identifier, index) => identifiers.indexOf(identifier) !== index);
+    if (duplicate !== undefined)
+        return rejected("duplicate-registration", duplicate);
+    if (!registry.workflows.includes(registration.workflowId))
+        return rejected("unresolved-workflow", registration.workflowId);
+    const missing = registration.steps.find((step) => !registry.steps.includes(step));
+    if (missing !== undefined)
+        return rejected("unresolved-step", missing);
+    return null;
+}
+function text(value) {
+    return value.trim().length > 0;
+}
+function distinctTexts(values) {
+    return values.every(text) && new Set(values).size === values.length;
+}
+function rejected(reason, detail) {
+    return { kind: "rejected", reason, detail };
+}
+function readRegistry(manifest) {
+    const categories = record(manifest);
+    if (!categories)
+        return null;
+    const workflows = identifiers(categories["workflows"], "workflowId");
+    const steps = identifiers(categories["steps"], "stepId");
+    if (!workflows || !steps)
+        return null;
+    return { workflows, steps };
+}
+function identifiers(category, key) {
+    const files = record(category);
+    if (!files)
+        return null;
+    const found = [];
+    for (const entries of Object.values(files)) {
+        const named = record(entries);
+        if (!named)
+            return null;
+        for (const entry of Object.values(named)) {
+            const identifier = record(entry)?.[key];
+            if (typeof identifier !== "string")
+                return null;
+            found.push(identifier);
+        }
+    }
+    return found;
+}
+function record(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    return Object.fromEntries(Object.entries(value));
+}