cloving 1.1.0 → 1.3.0

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/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 {};

package/dist/src/host/gate-bridge.js

@@ -0,0 +1,124 @@
+import { createHash } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
+import { gateKey } from "../authority/gates.js";
+import { decisionToken } from "../decision-wait.js";
+import { record } from "../protocol.js";
+const committed = ["accepted", "duplicate"];
+function promptDigest(request) {
+    return `sha256:${createHash("sha256").update(request.prompt).digest("hex")}`;
+}
+function sameHookSubject(value, request) {
+    const gate = record(value);
+    return (gate?.["subject"] === promptDigest(request) &&
+        gate["kind"] === request.kind &&
+        gate["wait"] === "hook");
+}
+async function paused(hold, milliseconds) {
+    await delay(milliseconds, undefined, { signal: hold.ports.stopped }).catch(() => undefined);
+    if (hold.ports.stopped.aborted)
+        await new Promise(() => undefined);
+}
+function verdict(hold, receipt) {
+    if (receipt === undefined || receipt.kind === "failed")
+        return hold.timing.retryMilliseconds;
+    if (committed.includes(receipt.kind))
+        return "committed";
+    if (receipt.reason === "service-busy")
+        return hold.timing.retryMilliseconds;
+    if (receipt.reason === "stale-revision")
+        return hold.timing.pollMilliseconds;
+    return { kind: "refused", reason: receipt.reason ?? receipt.kind };
+}
+async function gateCommand(hold, send) {
+    for (;;) {
+        await paused(hold, 0);
+        const result = verdict(hold, await send().catch(() => undefined));
+        if (result === "committed")
+            return undefined;
+        if (typeof result !== "number")
+            return result;
+        await paused(hold, result);
+    }
+}
+async function opening(hold, subject) {
+    const { runId, transport, request } = subject;
+    const { gateId, kind, prompt } = request;
+    const state = await hold.ports.state();
+    const run = state.runs[runId];
+    if (run === undefined)
+        return { kind: "rejected", reason: "unknown-run" };
+    const key = gateKey(runId, gateId);
+    const exists = Object.hasOwn(state.gates, key);
+    if (exists &&
+        subject.waitMode === "hook" &&
+        !sameHookSubject(state.gates[key], request))
+        return { kind: "rejected", reason: "gate-subject-changed" };
+    if (exists)
+        return { kind: "duplicate" };
+    return await hold.ports.openGate({
+        ...(subject.waitMode === undefined ? {} : { waitMode: subject.waitMode }),
+        runId,
+        commandId: `${transport}:open:${gateId}`,
+        expectedRevision: run.revision,
+        gateId,
+        kind,
+        prompt,
+        subject: promptDigest(request),
+        ...(request.expiresAt === undefined
+            ? {}
+            : { expiresAt: request.expiresAt }),
+    });
+}
+export async function openBridgeGate(ports, subject) {
+    const hold = {
+        ports,
+        timing: ports.timing ?? { pollMilliseconds: 20, retryMilliseconds: 1000 },
+    };
+    const refusal = await gateCommand(hold, () => opening(hold, subject));
+    if (refusal !== undefined)
+        return refusal;
+    if (subject.waitMode === "hook")
+        return {
+            kind: "opened",
+            decisionId: decisionToken(subject.runId, subject.request.gateId),
+        };
+    const waited = await gateCommand(hold, () => ports.registerWait({
+        runId: subject.runId,
+        commandId: `${subject.transport}:wait:${subject.request.gateId}`,
+        gateId: subject.request.gateId,
+    }));
+    return waited ?? { kind: "opened", decisionId: subject.request.gateId };
+}
+export async function waitForBridgeDecision(ports, subject) {
+    const hold = {
+        ports,
+        timing: ports.timing ?? { pollMilliseconds: 20, retryMilliseconds: 1000 },
+    };
+    await paused(hold, 0);
+    const state = await ports.state();
+    const key = gateKey(subject.runId, subject.request.gateId);
+    const gate = state.gates[key];
+    if (Object.hasOwn(state.gates, key) &&
+        !sameHookSubject(gate, subject.request))
+        throw new Error("gate-subject-changed");
+    const outcome = record(record(gate)?.["outcome"]);
+    if (outcome !== undefined &&
+        (await ports.decisionReceived(subject.runId, subject.request.gateId)))
+        return await storedDecision(ports, outcome);
+    const opening = await openBridgeGate(ports, { ...subject, waitMode: "hook" });
+    if (opening.kind !== "opened")
+        throw new Error(opening.reason);
+    return { token: opening.decisionId };
+}
+async function storedDecision(ports, outcome) {
+    const decision = ["approved", "denied", "answered", "expired"].find((value) => value === outcome["decision"]);
+    if (decision === undefined)
+        throw new Error("invalid-decision-outcome");
+    const digest = outcome["answer"];
+    if (digest !== null && typeof digest !== "string")
+        throw new Error("invalid-decision-answer");
+    const answer = digest === null ? null : await ports.document(digest);
+    if (answer === undefined)
+        throw new Error("missing-decision-answer");
+    return { decision, answer };
+}

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

@@ -0,0 +1,26 @@
+import { type RunWaitTarget } from "../run-wait.ts";
+import type { RunWaitOutcome, RunWaitRequest } from "../step-bridge.ts";
+export interface RunWaitPorts {
+    readonly now?: () => number;
+    readonly target: (runId: string) => Promise<RunWaitTarget | undefined>;
+    readonly observe: (report: {
+        readonly runId: string;
+        readonly commandId: string;
+        readonly condition: string;
+        readonly reason: string;
+        readonly evidence?: string;
+        readonly retryAt?: string;
+        readonly operationId?: string;
+    }) => Promise<{
+        readonly kind: string;
+        readonly reason?: string;
+    }>;
+}
+export declare function runWait(ports: RunWaitPorts, wait: {
+    readonly caller: {
+        readonly runId: string;
+        readonly stepId: string;
+        readonly startedAt: number;
+    };
+    readonly request: RunWaitRequest;
+}): Promise<RunWaitOutcome>;

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

@@ -0,0 +1,37 @@
+import { FatalError, RetryableError } from "workflow";
+import { runWaitResult } from "../run-wait.js";
+export async function runWait(ports, wait) {
+    const { caller, request } = wait;
+    const now = (ports.now ?? Date.now)();
+    const result = runWaitResult(request, {
+        callerRunId: caller.runId,
+        startedAt: caller.startedAt,
+        now,
+        target: await ports.target(request.runId),
+    });
+    const waiting = result.kind === "waiting";
+    const receipt = await ports.observe({
+        runId: caller.runId,
+        commandId: `${caller.stepId}:run-wait:${waiting ? "waiting" : "ended"}`,
+        condition: waiting ? "waiting-run" : "working",
+        reason: waiting ? "awaiting-run" : "in-progress",
+        operationId: caller.stepId,
+        ...(result.kind !== "waiting"
+            ? {}
+            : {
+                evidence: request.runId,
+                retryAt: new Date(result.deadline).toISOString(),
+            }),
+    });
+    if (!["accepted", "duplicate"].includes(receipt.kind))
+        throw new RetryableError("run-wait-observation-unavailable", {
+            retryAfter: 1000,
+        });
+    if (result.kind === "refused")
+        throw new FatalError(result.reason);
+    if (result.kind === "completed")
+        return result.outcome;
+    throw new RetryableError("awaiting-run", {
+        retryAfter: Math.max(1, Math.min(1000, result.deadline - now)),
+    });
+}

package/dist/src/host/start-delivery.d.ts

@@ -9,6 +9,7 @@ export interface RunIntent extends Partial<Continuation> {
     readonly kind: string;
     readonly runId: string;
     readonly operationId: string;
+    readonly workflow: string;
 }
 export type RunOutcome = {
     readonly kind: "accepted";
@@ -27,12 +28,12 @@ export interface StartParts {
     readonly runs: () => Promise<readonly OperationRun[]>;
     readonly input: (runId: string) => Promise<string | undefined>;
     readonly document: (digest: string) => Promise<string | undefined>;
-    readonly workflow: (runId: string) => Promise<WorkflowFunction | undefined>;
+    readonly workflow: (intent: RunIntent) => Promise<WorkflowFunction | undefined>;
     readonly cancel: (receipt: string) => Promise<string>;
 }
 export interface StartDelivery {
     readonly reconcile: (intent: RunIntent) => Promise<RunOutcome>;
-    readonly deliver: (intent: RunIntent) => Promise<{
+    readonly deliver: (intent: RunIntent, signal?: AbortSignal) => Promise<{
         readonly receipt: string;
     }>;
     readonly stop: (intent: RunIntent) => Promise<RunOutcome>;

package/dist/src/host/start-delivery.js

@@ -1,5 +1,6 @@
 import { start } from "workflow/api";
 import { operationTag, runTag } from "./world-runs.js";
+import { deliveredDecision, reconciledDecision, stoppedDecision, } from "./decision-resume.js";
 const ends = ["cancelled", "completed", "failed"];
 async function segments(parts, intent) {
     return (await parts.runs()).filter((run) => run.operationId === intent.operationId);
@@ -31,7 +32,7 @@ async function continuation(parts, intent) {
 }
 async function delivered(parts, intent) {
     const continued = await continuation(parts, intent);
-    const workflow = await parts.workflow(intent.runId);
+    const workflow = await parts.workflow(intent);
     const input = await parts.input(intent.runId);
     if (workflow === undefined || input === undefined)
         throw new Error(`start-not-available: ${intent.runId}`);
@@ -61,8 +62,14 @@ async function stopped(parts, intent) {
 }
 export function startDelivery(parts) {
     return {
-        reconcile: (intent) => reconciled(parts, intent),
-        deliver: (intent) => delivered(parts, intent),
-        stop: (intent) => stopped(parts, intent),
+        reconcile: (intent) => intent.kind === "resume-hook"
+            ? reconciledDecision(parts, intent)
+            : reconciled(parts, intent),
+        deliver: (intent, signal) => intent.kind === "resume-hook"
+            ? deliveredDecision(parts, { intent, signal })
+            : delivered(parts, intent),
+        stop: (intent) => intent.kind === "resume-hook"
+            ? stoppedDecision(parts, intent)
+            : stopped(parts, intent),
     };
 }

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

@@ -1,8 +1,12 @@
+import { type GateOpening, type GateReceipt, type WaitRegistration } from "./gate-bridge.ts";
+export type { GateOpening, GateReceipt, WaitRegistration, } from "./gate-bridge.ts";
+import { type RunWaitPorts } from "./run-wait.ts";
 import { type ProtectedRequest, type StepBridge } from "../step-bridge.ts";
 export interface StepCall {
     readonly worldRunId: string;
     readonly stepId: string;
     readonly attempt: number;
+    readonly startedAt?: number;
 }
 export declare function sdkStepCall(): StepCall;
 export interface OperationRead {
@@ -30,24 +34,6 @@ interface BridgeIdentity {
 export interface BridgeRequest extends ProtectedRequest, BridgeIdentity {
     readonly runId: string;
 }
-export interface GateReceipt {
-    readonly kind: string;
-    readonly reason?: string;
-}
-export interface GateOpening {
-    readonly runId: string;
-    readonly commandId: string;
-    readonly expectedRevision: number;
-    readonly gateId: string;
-    readonly kind: "question" | "approval";
-    readonly prompt: string;
-    readonly subject: string;
-}
-export interface WaitRegistration {
-    readonly runId: string;
-    readonly commandId: string;
-    readonly gateId: string;
-}
 export interface BridgeTiming {
     readonly lookupTries: number;
     readonly pollMilliseconds: number;
@@ -55,6 +41,8 @@ export interface BridgeTiming {
 }
 export declare const bridgeTiming: BridgeTiming;
 export interface BridgePorts {
+    readonly decisionReceived?: (runId: string, gateId: string) => Promise<boolean>;
+    readonly runWait?: RunWaitPorts;
     readonly call: () => StepCall;
     readonly run: (worldRunId: string) => Promise<{
         readonly runId: string;
@@ -76,4 +64,3 @@ export interface BridgePorts {
 }
 export declare function stepBridge(ports: BridgePorts): StepBridge;
 export declare function registerStepBridge(bridge: StepBridge): () => void;
-export {};