cloving 1.2.0 → 1.4.0

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;

package/dist/src/harness-defaults.js

@@ -0,0 +1,121 @@
+export const defaultCommand = [
+    "claude",
+    "-p",
+    "--output-format",
+    "stream-json",
+    "--verbose",
+    "--permission-mode",
+    "acceptEdits",
+    "--allowedTools",
+    "Bash,Read,Edit,Write,Glob,Grep,WebSearch,WebFetch",
+    "--max-budget-usd",
+    "5",
+];
+export const defaultCodexCommand = [
+    "codex",
+    "exec",
+    "--json",
+    "--dangerously-bypass-approvals-and-sandbox",
+    "--skip-git-repo-check",
+    "-",
+];
+export const defaultGeminiCommand = [
+    "gemini",
+    "--output-format",
+    "stream-json",
+    "--approval-mode",
+    "yolo",
+];
+export const defaultCursorCommand = [
+    "cursor-agent",
+    "-p",
+    "--output-format",
+    "stream-json",
+    "--force",
+];
+export const defaultOpencodeCommand = ["opencode", "run", "--format", "json"];
+export const defaultGrokCommand = [
+    "grok",
+    "--output-format",
+    "streaming-messages-json",
+    "--always-approve",
+    "-p",
+];
+const defaultCommands = {
+    claude: defaultCommand,
+    codex: defaultCodexCommand,
+    gemini: defaultGeminiCommand,
+    grok: defaultGrokCommand,
+    opencode: defaultOpencodeCommand,
+    "cursor-agent": defaultCursorCommand,
+};
+function matchingHarness(settings, name) {
+    return (settings.harness?.name ?? "claude") === name
+        ? (settings.harness ?? {})
+        : {};
+}
+function nativeCommand(settings, name) {
+    const command = settings.workerCommands?.[name];
+    if (command !== undefined)
+        return command;
+    if (name === (settings.worker ?? "claude") && settings.command !== undefined)
+        return settings.command;
+    const saved = matchingHarness(settings, name);
+    if (saved.command !== undefined)
+        return saved.command;
+    const defaults = harnessDefaults(name).command;
+    return [saved.path ?? name, ...defaults.slice(1)];
+}
+export function isTurnCommand(value) {
+    if (!Array.isArray(value))
+        return false;
+    const program = value[0];
+    return (typeof program === "string" &&
+        program !== "" &&
+        program !== "{prompt}" &&
+        value.every((part) => typeof part === "string" && !part.includes("\u0000")) &&
+        value.filter((part) => part === "{prompt}").length <= 1);
+}
+export function harnessDefaults(value) {
+    const name = typeof value === "string" && nativeHarness(value) ? value : "claude";
+    const variable = {
+        claude: "CLOVING_CLAUDE_COMMAND",
+        codex: "CLOVING_CODEX_COMMAND",
+        gemini: "CLOVING_GEMINI_COMMAND",
+        grok: "CLOVING_GROK_COMMAND",
+        opencode: "CLOVING_OPENCODE_COMMAND",
+        "cursor-agent": undefined,
+    }[name];
+    return {
+        command: defaultCommands[name],
+        ...(variable === undefined ? {} : { variable }),
+    };
+}
+function selectedCommand(settings, name) {
+    if (nativeHarness(name))
+        return { command: nativeCommand(settings, name) };
+    const saved = matchingHarness(settings, name);
+    if (saved.turn === undefined)
+        throw new Error(`harness-no-worker: ${name}`);
+    if (!isTurnCommand(saved.turn))
+        throw new Error("invalid-setting: harness.turn");
+    return {
+        command: saved.command ?? [
+            saved.path ?? saved.turn[0] ?? "",
+            ...saved.turn.slice(1),
+        ],
+        output: "text",
+    };
+}
+export function turnHarness(settings, profile = {}) {
+    const name = profile.harness ?? settings.worker ?? settings.harness?.name ?? "claude";
+    const saved = matchingHarness(settings, name);
+    return {
+        worker: name,
+        ...selectedCommand(settings, name),
+        ...(saved.kind === "shell" ? { shell: settings.shell ?? "/bin/sh" } : {}),
+    };
+}
+export function nativeHarness(name) {
+    return Object.hasOwn(defaultCommands, name);
+}

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

@@ -0,0 +1,15 @@
+import { type ShellMode } from "./agent-harness-shell.ts";
+import type { HarnessSelection } from "./configuration-change.ts";
+export interface HarnessStartRequest {
+    readonly executable: string;
+    readonly arguments: readonly string[];
+    readonly directory: string;
+    readonly environment: Readonly<Record<string, string | undefined>>;
+}
+export declare function harnessStartRequest(entry: HarnessSelection & {
+    readonly shellMode?: ShellMode;
+}, context: {
+    readonly repository: string;
+    readonly environment: Readonly<NodeJS.ProcessEnv>;
+    readonly message: string;
+}): HarnessStartRequest;

package/dist/src/harness-start.js

@@ -0,0 +1,37 @@
+import { shellArguments, shellRunScript, } from "./agent-harness-shell.js";
+const shellStartScript = `
+set +m
+kind=
+if [ -n "\${ZSH_VERSION-}" ]; then
+  kind=$(builtin whence -w -- "$1" 2>/dev/null) || kind=
+  kind="\${kind##*: }"
+elif [ -n "\${BASH_VERSION-}" ]; then
+  kind=$(builtin type -t -- "$1" 2>/dev/null) || kind=
+fi
+case "$kind" in
+  function|alias) ;;
+  *) printf '%s\\n' 'Open your agent in this repository and tell it: run \`cloving init-prompt\`.' >&2; exit 1 ;;
+esac
+${shellRunScript}
+`;
+export function harnessStartRequest(entry, context) {
+    const argumentsList = entry.name === "opencode"
+        ? ["--prompt", context.message]
+        : [context.message];
+    const executable = entry.kind === "shell" ? (context.environment["SHELL"] ?? "") : entry.path;
+    const args = entry.kind === "shell"
+        ? [
+            ...shellArguments(entry.shellMode ?? "login"),
+            shellStartScript,
+            "cloving-init",
+            entry.path,
+            ...argumentsList,
+        ]
+        : argumentsList;
+    return {
+        executable,
+        arguments: args,
+        directory: context.repository,
+        environment: context.environment,
+    };
+}

package/dist/src/host/command-wait.d.ts

@@ -0,0 +1,38 @@
+import type { CommandWaitState } from "../authority/command-waits.ts";
+import type { CommandWaitRequest, CommandWaitProgress } from "../step-bridge.ts";
+interface WaitName {
+    readonly runId: string;
+    readonly name: string;
+}
+interface WaitCall extends WaitName {
+    readonly commandId: string;
+}
+interface WaitReceipt {
+    readonly kind: string;
+    readonly reason?: string;
+}
+export interface CommandWaitPorts {
+    readonly open: (request: WaitCall & {
+        readonly input: string;
+    }) => Promise<WaitReceipt>;
+    readonly check: (request: WaitCall) => Promise<WaitReceipt>;
+    readonly read: (request: WaitName) => Promise<CommandWaitState | undefined>;
+}
+interface WaitHost {
+    readonly commandWait?: CommandWaitPorts;
+    readonly runStatus: (runId: string) => Promise<string | undefined>;
+    readonly subject: () => Promise<{
+        readonly runId: string;
+        readonly commandId: string;
+    } | undefined>;
+    readonly stopped: AbortSignal;
+    readonly pollMilliseconds: number;
+    readonly retryMilliseconds: number;
+}
+export declare function commandWaitBridge(host: WaitHost): {
+    openCommandWait: (request: CommandWaitRequest) => Promise<CommandWaitProgress>;
+    checkCommandWait: (request: {
+        readonly name: string;
+    }) => Promise<CommandWaitProgress>;
+};
+export {};

package/dist/src/host/command-wait.js

@@ -0,0 +1,115 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { commandWaitValue, isCommandWaitRequest } from "../command-wait.js";
+function progress(wait) {
+    if (wait === undefined)
+        return { kind: "refused", reason: "unknown-command-wait" };
+    if (wait.state === "waiting")
+        return waiting(wait);
+    if (wait.state === "timed-out")
+        return { kind: "timed-out", reason: "command-wait-timeout" };
+    if (wait.state !== "completed")
+        return { kind: "failed", reason: wait.reason ?? "command-wait-failed" };
+    const value = JSON.parse(wait.result ?? "null");
+    return commandWaitValue(value)
+        ? { kind: "ready", value }
+        : { kind: "failed", reason: "command-wait-invalid-output" };
+}
+function refused(receipt) {
+    if (["accepted", "duplicate"].includes(receipt.kind))
+        return undefined;
+    return {
+        kind: receipt.kind === "failed" ? "failed" : "refused",
+        reason: receipt.reason ?? receipt.kind,
+    };
+}
+async function requested(context, send) {
+    const { host, call, retryReasons = ["service-busy"] } = context;
+    for (;;) {
+        if (host.stopped.aborted)
+            await new Promise(() => undefined);
+        const receipt = await send();
+        if (receipt.kind !== "rejected" ||
+            !retryReasons.includes(receipt.reason ?? ""))
+            return receipt;
+        if (receipt.reason === "command-wait-run-not-running" &&
+            !["queued", "running", "waiting_gate", "paused"].includes((await host.runStatus(call.runId)) ?? ""))
+            return receipt;
+        await delay(host.retryMilliseconds, undefined, {
+            signal: host.stopped,
+        }).catch(() => undefined);
+    }
+}
+async function settled(context, request) {
+    const { host, port } = context;
+    for (;;) {
+        if (host.stopped.aborted)
+            await new Promise(() => undefined);
+        const wait = await port.read(request);
+        if (wait?.state !== "waiting" || wait.checkOperation === null)
+            return progress(wait);
+        await delay(host.pollMilliseconds, undefined, {
+            signal: host.stopped,
+        }).catch(() => undefined);
+    }
+}
+export function commandWaitBridge(host) {
+    return {
+        openCommandWait: async (request) => {
+            if (!isCommandWaitRequest(request))
+                return { kind: "refused", reason: "invalid-command-wait-request" };
+            const subject = await host.subject();
+            const port = host.commandWait;
+            if (subject === undefined || port === undefined)
+                return { kind: "unavailable", reason: "cloving-host-unavailable" };
+            const call = {
+                ...subject,
+                name: request.name,
+                input: JSON.stringify(request.input),
+            };
+            const receipt = await requested({
+                host,
+                call,
+                retryReasons: ["service-busy", "command-wait-run-not-running"],
+            }, () => port.open(call));
+            return (refused(receipt) ??
+                progress(await port.read({ ...subject, name: request.name })));
+        },
+        checkCommandWait: async (request) => {
+            const subject = await host.subject();
+            const port = host.commandWait;
+            if (subject === undefined || port === undefined)
+                return { kind: "unavailable", reason: "cloving-host-unavailable" };
+            const call = { ...subject, name: request.name };
+            const wait = await port.read(call);
+            if (wait?.state !== "waiting")
+                return progress(wait);
+            if (wait.checkOperation !== null)
+                return await settled({ host, port }, call);
+            if (wait.nextCheckAt !== null &&
+                Date.now() < Math.min(wait.nextCheckAt, wait.deadline))
+                return progress(wait);
+            const receipt = await requested({ host, call }, () => port.check(call));
+            return checkReply(receipt, wait) ?? (await settled({ host, port }, call));
+        },
+    };
+}
+function checkReply(receipt, wait) {
+    if (receipt.reason === "command-wait-timeout")
+        return { kind: "timed-out", reason: receipt.reason };
+    if (receipt.reason === "command-wait-run-not-running")
+        return waiting(wait, Date.now() + 1000);
+    if ([
+        "command-wait-check-in-flight",
+        "command-wait-check-not-due",
+        "command-wait-ended",
+    ].includes(receipt.reason ?? ""))
+        return undefined;
+    return refused(receipt);
+}
+function waiting(wait, nextCheckAt = wait.nextCheckAt ?? wait.deadline) {
+    return {
+        kind: "pending",
+        deadline: wait.deadline,
+        nextCheckAt,
+    };
+}

package/dist/src/host/decision-resume.d.ts

@@ -0,0 +1,35 @@
+interface RunIntent {
+    readonly runId: string;
+    readonly gateId?: string;
+    readonly decision?: string;
+    readonly answer?: string | null;
+}
+interface ResumeParts {
+    readonly runs: () => Promise<readonly {
+        readonly operationId: string | null;
+        readonly receipt: string;
+    }[]>;
+    readonly document: (digest: string) => Promise<string | undefined>;
+}
+export declare function reconciledDecision(parts: ResumeParts, intent: RunIntent): Promise<{
+    readonly kind: "accepted";
+    readonly receipt: string;
+} | {
+    readonly kind: "absent";
+}>;
+export declare function deliveredDecision(parts: ResumeParts, request: {
+    readonly intent: RunIntent;
+    readonly signal: AbortSignal | undefined;
+}): Promise<{
+    readonly receipt: string;
+}>;
+export declare function stoppedDecision(parts: ResumeParts & {
+    readonly cancel: (receipt: string) => Promise<string>;
+}, intent: RunIntent): Promise<{
+    readonly kind: "stopped";
+    readonly receipt: string;
+} | {
+    readonly kind: "unknown";
+    readonly evidence: string;
+}>;
+export {};

package/dist/src/host/decision-resume.js

@@ -0,0 +1,86 @@
+import { resumeHook } from "workflow/api";
+import { getWorld } from "workflow/runtime";
+import { setTimeout as delay } from "node:timers/promises";
+import { decisionToken } from "../decision-wait.js";
+import { namesRunIntent } from "../authority/operations.js";
+async function runSubject(receipt, token) {
+    const world = await getWorld();
+    let page = await world.events.list({
+        runId: receipt,
+        resolveData: "none",
+        pagination: { limit: 1000, sortOrder: "asc" },
+    });
+    const events = [...page.data];
+    while (page.hasMore && page.cursor !== null) {
+        page = await world.events.list({
+            runId: receipt,
+            resolveData: "none",
+            pagination: { limit: 1000, sortOrder: "asc", cursor: page.cursor },
+        });
+        events.push(...page.data);
+    }
+    const created = events.find((event) => event.eventType === "hook_created" && event.eventData.token === token);
+    const hookId = created?.correlationId;
+    return {
+        runId: receipt,
+        token,
+        hookId,
+        received: hookId !== undefined &&
+            events.some((event) => event.eventType === "hook_received" && event.correlationId === hookId),
+    };
+}
+async function subject(parts, intent) {
+    if (intent.gateId === undefined)
+        throw new Error("missing-decision-gate");
+    const token = decisionToken(intent.runId, intent.gateId);
+    const runs = (await parts.runs()).filter((run) => namesRunIntent(run.operationId ?? "", intent.runId));
+    const latest = runs.at(-1);
+    if (latest === undefined)
+        throw new Error("missing-decision-run");
+    const matches = [];
+    for (const run of runs) {
+        const found = await runSubject(run.receipt, token);
+        if (found.hookId !== undefined)
+            matches.push(found);
+    }
+    if (matches.length > 1)
+        throw new Error("conflicting-decision-hooks");
+    return (matches[0] ?? {
+        runId: latest.receipt,
+        token,
+        hookId: undefined,
+        received: false,
+    });
+}
+export async function reconciledDecision(parts, intent) {
+    const found = await subject(parts, intent);
+    return found.received
+        ? { kind: "accepted", receipt: found.runId }
+        : { kind: "absent" };
+}
+export async function deliveredDecision(parts, request) {
+    const { intent, signal } = request;
+    let found = await subject(parts, intent);
+    while (!found.received && found.hookId === undefined) {
+        await delay(20, undefined, signal === undefined ? {} : { signal });
+        found = await subject(parts, intent);
+    }
+    if (found.received)
+        return { receipt: found.runId };
+    if (intent.decision === undefined)
+        throw new Error("missing-decision");
+    const answer = intent.answer === undefined || intent.answer === null
+        ? null
+        : await parts.document(intent.answer);
+    if (answer === undefined)
+        throw new Error("missing-decision-answer");
+    await resumeHook(found.token, { decision: intent.decision, answer });
+    return { receipt: found.runId };
+}
+export async function stoppedDecision(parts, intent) {
+    const found = await subject(parts, intent);
+    const status = await parts.cancel(found.runId);
+    return ["cancelled", "completed", "failed"].includes(status)
+        ? { kind: "stopped", receipt: found.runId }
+        : { kind: "unknown", evidence: `world-run:${found.runId} ${status}` };
+}

package/dist/src/host/gate-bridge.d.ts

@@ -0,0 +1,48 @@
+import type { DecisionWait, GateRequest, GateResult } from "../step-bridge.ts";
+export interface GateReceipt {
+    readonly kind: string;
+    readonly reason?: string;
+}
+export interface GateOpening {
+    readonly waitMode?: "hook";
+    readonly runId: string;
+    readonly commandId: string;
+    readonly expectedRevision: number;
+    readonly gateId: string;
+    readonly kind: "question" | "approval";
+    readonly prompt: string;
+    readonly subject: string;
+    readonly expiresAt?: string;
+}
+export interface WaitRegistration {
+    readonly runId: string;
+    readonly commandId: string;
+    readonly gateId: string;
+}
+interface GatePorts {
+    readonly stopped: AbortSignal;
+    readonly timing?: {
+        readonly pollMilliseconds: number;
+        readonly retryMilliseconds: number;
+    };
+    readonly state: () => Promise<{
+        readonly runs: Readonly<Record<string, {
+            readonly revision: number;
+        } | undefined>>;
+        readonly gates: Readonly<Record<string, unknown>>;
+    }>;
+    readonly openGate: (opening: GateOpening) => Promise<GateReceipt>;
+    readonly registerWait: (wait: WaitRegistration) => Promise<GateReceipt>;
+}
+interface GateSubject {
+    readonly waitMode?: "hook";
+    readonly runId: string;
+    readonly transport: string;
+    readonly request: GateRequest;
+}
+export declare function openBridgeGate(ports: GatePorts, subject: GateSubject): Promise<GateResult>;
+export declare function waitForBridgeDecision(ports: GatePorts & {
+    readonly document: (digest: string) => Promise<string | undefined>;
+    readonly decisionReceived: (runId: string, gateId: string) => Promise<boolean>;
+}, subject: GateSubject): Promise<DecisionWait>;
+export {};