cloving 1.2.0 → 1.4.0

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

@@ -1,11 +1,9 @@
 import { type TaggedRun } from "./world-runs.ts";
-export type WorkflowFunction = (input: unknown, continuation?: Continuation) => Promise<unknown>;
-export interface Continuation {
-    readonly gateId: string;
-    readonly decision: string;
-    readonly answer: string | null;
-}
-export interface RunIntent extends Partial<Continuation> {
+export type WorkflowFunction = (input: unknown) => Promise<unknown>;
+export interface RunIntent {
+    readonly gateId?: string;
+    readonly decision?: string;
+    readonly answer?: string | null;
     readonly kind: string;
     readonly runId: string;
     readonly operationId: string;
@@ -33,7 +31,7 @@ export interface StartParts {
 }
 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);
@@ -16,27 +17,15 @@ async function reconciled(parts, intent) {
         evidence: found.map((run) => `world-run:${run.receipt}`).join(" "),
     };
 }
-async function continuation(parts, intent) {
-    const { kind, gateId, decision, answer } = intent;
-    if (kind === "start-run")
-        return undefined;
-    if (kind !== "continue-run" || gateId === undefined || decision === undefined)
-        throw new Error(`unsupported-intent: ${kind}`);
-    if (answer === undefined || answer === null)
-        return { gateId, decision, answer: null };
-    const text = await parts.document(answer);
-    if (text === undefined)
-        throw new Error(`answer-not-available: ${gateId}`);
-    return { gateId, decision, answer: text };
-}
 async function delivered(parts, intent) {
-    const continued = await continuation(parts, intent);
+    if (intent.kind !== "start-run")
+        throw new Error(`unsupported-intent: ${intent.kind}`);
     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}`);
     const argument = JSON.parse(input);
-    const started = await start(workflow, [argument, continued], {
+    const started = await start(workflow, [argument], {
         attributes: {
             [runTag]: intent.runId,
             [operationTag]: intent.operationId,
@@ -61,8 +50,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,13 @@
+import { type CommandWaitPorts } from "./command-wait.ts";
+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,25 +35,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;
-    readonly expiresAt?: string;
-}
-export interface WaitRegistration {
-    readonly runId: string;
-    readonly commandId: string;
-    readonly gateId: string;
-}
 export interface BridgeTiming {
     readonly lookupTries: number;
     readonly pollMilliseconds: number;
@@ -56,6 +42,9 @@ export interface BridgeTiming {
 }
 export declare const bridgeTiming: BridgeTiming;
 export interface BridgePorts {
+    readonly commandWait?: CommandWaitPorts;
+    readonly decisionReceived?: (runId: string, gateId: string) => Promise<boolean>;
+    readonly runWait?: RunWaitPorts;
     readonly call: () => StepCall;
     readonly run: (worldRunId: string) => Promise<{
         readonly runId: string;
@@ -77,4 +66,3 @@ export interface BridgePorts {
 }
 export declare function stepBridge(ports: BridgePorts): StepBridge;
 export declare function registerStepBridge(bridge: StepBridge): () => void;
-export {};

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

@@ -1,11 +1,20 @@
+import { commandWaitBridge } from "./command-wait.js";
 import { createHash } from "node:crypto";
 import { setTimeout as delay } from "node:timers/promises";
 import { getStepMetadata, getWorkflowMetadata } from "workflow";
-import { gateKey } from "../authority/gates.js";
+import { openBridgeGate, waitForBridgeDecision, } from "./gate-bridge.js";
+import { runWait } from "./run-wait.js";
+import { reconciledDecision } from "./decision-resume.js";
+import { taggedRuns } from "./world-runs.js";
 import { stepBridgeKey, } from "../step-bridge.js";
 export function sdkStepCall() {
-    const { stepId, attempt } = getStepMetadata();
-    return { worldRunId: getWorkflowMetadata().workflowRunId, stepId, attempt };
+    const { stepId, attempt, stepStartedAt } = getStepMetadata();
+    return {
+        worldRunId: getWorkflowMetadata().workflowRunId,
+        stepId,
+        attempt,
+        startedAt: stepStartedAt.getTime(),
+    };
 }
 export const bridgeTiming = {
     lookupTries: 250,
@@ -129,74 +138,72 @@ async function effect(hold, request) {
         return answer;
     return await settled(hold, answer.operationId);
 }
-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" };
-    if (Object.hasOwn(state.gates, gateKey(runId, gateId)))
-        return { kind: "duplicate" };
-    return await hold.ports.openGate({
-        runId,
-        commandId: `${transport}:open:${gateId}`,
-        expectedRevision: run.revision,
-        gateId,
-        kind,
-        prompt,
-        subject: `sha256:${createHash("sha256").update(prompt).digest("hex")}`,
-        ...(request.expiresAt === undefined
-            ? {}
-            : { expiresAt: request.expiresAt }),
-    });
-}
-async function gate(hold, request) {
+async function gateSubject(hold, request) {
     const call = hold.ports.call();
     const world = await located(hold, call.worldRunId);
     if (world === undefined)
-        return { kind: "unavailable", reason: "unknown-world-run" };
+        return undefined;
     await inWork(hold, world.runId);
-    const subject = {
+    return {
+        request,
         runId: world.runId,
         transport: transportOf(call),
-        request,
     };
-    const refusal = (await gateCommand(hold, () => opening(hold, subject))) ??
-        (await gateCommand(hold, () => hold.ports.registerWait({
-            runId: subject.runId,
-            commandId: `${subject.transport}:wait:${request.gateId}`,
-            gateId: request.gateId,
-        })));
-    return refusal ?? { kind: "opened", decisionId: request.gateId };
+}
+async function gate(hold, request) {
+    const subject = await gateSubject(hold, request);
+    if (subject === undefined)
+        return { kind: "unavailable", reason: "unknown-world-run" };
+    return await openBridgeGate(hold.ports, subject);
+}
+function hostCommandWait(hold) {
+    return commandWaitBridge({
+        ...(hold.ports.commandWait === undefined
+            ? {}
+            : { commandWait: hold.ports.commandWait }),
+        stopped: hold.ports.stopped,
+        pollMilliseconds: hold.timing.pollMilliseconds,
+        retryMilliseconds: hold.timing.retryMilliseconds,
+        runStatus: async (runId) => (await hold.ports.state()).runs[runId]?.status,
+        subject: async () => {
+            const call = hold.ports.call();
+            const world = await located(hold, call.worldRunId);
+            if (world === undefined)
+                return undefined;
+            await inWork(hold, world.runId);
+            return { runId: world.runId, commandId: transportOf(call) };
+        },
+    });
 }
 export function stepBridge(ports) {
     const hold = { ports, timing: ports.timing ?? bridgeTiming };
     return {
+        ...hostCommandWait(hold),
         effect: (request) => effect(hold, request),
         gate: (request) => gate(hold, request),
+        waitForDecision: async (request) => {
+            const subject = await gateSubject(hold, request);
+            if (subject === undefined)
+                throw new Error("unknown-world-run");
+            return await waitForBridgeDecision({
+                ...ports,
+                decisionReceived: ports.decisionReceived ??
+                    (async (runId, gateId) => (await reconciledDecision({ runs: taggedRuns, document: ports.document }, { runId, gateId })).kind === "accepted"),
+            }, subject);
+        },
+        waitForRun: async (request) => {
+            const call = ports.call();
+            const world = await located(hold, call.worldRunId);
+            if (world === undefined ||
+                ports.runWait === undefined ||
+                call.startedAt === undefined)
+                throw new Error("cloving-host-unavailable");
+            await inWork(hold, world.runId);
+            return await runWait(ports.runWait, {
+                caller: { ...world, stepId: call.stepId, startedAt: call.startedAt },
+                request,
+            });
+        },
         handoff: (request) => effect(hold, {
             scope: {
                 phase: "handoff",

package/dist/src/merge-request.d.ts

@@ -0,0 +1,19 @@
+export interface PullRequest {
+    readonly number: number;
+    readonly url: string;
+    readonly commit: string;
+    readonly target: string;
+}
+export type MergeCheckName = "beforeMerge";
+export interface MergeRequest {
+    readonly pull: PullRequest;
+    readonly check: MergeCheckName | null;
+    readonly round?: number;
+}
+export type MergeReason = "check-failed" | "merge-conflict" | "ci-failed" | "ci-pending" | "check-not-configured" | "not-approved";
+export interface MergeResult {
+    readonly merged: boolean;
+    readonly reason: MergeReason | null;
+    readonly output: string;
+}
+export declare function mergeRequest(value: unknown): Required<MergeRequest>;

package/dist/src/merge-request.js

@@ -0,0 +1,32 @@
+import { record } from "./protocol.js";
+import { commitId } from "./review-subject.js";
+export function mergeRequest(value) {
+    const request = record(value);
+    const pull = pullRequest(request?.["pull"]);
+    const check = request?.["check"];
+    if (request === undefined ||
+        pull === undefined ||
+        !Object.hasOwn(request, "check") ||
+        (check !== null && check !== "beforeMerge"))
+        throw new Error("invalid-merge-request");
+    return { pull, check, round: mergeRound(request["round"] ?? 1) };
+}
+function mergeRound(value) {
+    if (!positiveInteger(value))
+        throw new Error("invalid-merge-request");
+    return value;
+}
+function pullRequest(value) {
+    const pull = record(value);
+    const { number, url, commit, target } = pull ?? {};
+    if (!positiveInteger(number) ||
+        typeof url !== "string" ||
+        !commitId(commit) ||
+        typeof target !== "string" ||
+        target.trim() === "")
+        return undefined;
+    return { number, url, commit, target };
+}
+function positiveInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}

package/dist/src/operation-identity.d.ts

@@ -5,3 +5,4 @@ export interface OperationScope {
     readonly operation: string;
 }
 export declare function operationScope(operationId: string): OperationScope | null;
+export declare function operationPhase(operationId: string): string | null;

package/dist/src/operation-identity.js

@@ -48,6 +48,10 @@ export function operationScope(operationId) {
         return null;
     return { run, operation };
 }
+export function operationPhase(operationId) {
+    const [marker, , , phase] = parsedList(operationId);
+    return marker === "cloving-operation" && isComponent(phase) ? phase : null;
+}
 function parsedList(text) {
     try {
         const value = JSON.parse(text);

package/dist/src/phone/canonical-json.d.ts

@@ -0,0 +1 @@
+export declare function canonicalJson(value: unknown): string;

package/dist/src/phone/canonical-json.js

@@ -0,0 +1,16 @@
+export function canonicalJson(value) {
+    if (value === null || typeof value === "boolean" || typeof value === "string")
+        return JSON.stringify(value);
+    if (typeof value === "number" && !Number.isSafeInteger(value))
+        throw new Error("canonical-json-number: Only safe integers are allowed.");
+    if (typeof value === "number")
+        return String(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (typeof value !== "object")
+        throw new Error("canonical-json-value: The value is not JSON.");
+    const fields = Object.keys(value)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${canonicalJson(Reflect.get(value, key))}`);
+    return `{${fields.join(",")}}`;
+}

package/dist/src/phone/phone-link.d.ts

@@ -0,0 +1,7 @@
+export interface PhoneLink {
+    readonly daemonId: string;
+    readonly origin: string;
+    readonly token: string;
+    readonly registeredAt: string;
+}
+export declare function parsePhoneLink(text: string | undefined): PhoneLink | undefined;

package/dist/src/phone/phone-link.js

@@ -0,0 +1,21 @@
+export function parsePhoneLink(text) {
+    if (text === undefined)
+        return undefined;
+    const value = JSON.parse(text);
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const filled = (name) => {
+        const field = Reflect.get(value, name);
+        return typeof field === "string" && field !== "" ? field : undefined;
+    };
+    const daemonId = filled("daemonId");
+    const origin = filled("origin");
+    const token = filled("token");
+    const registeredAt = filled("registeredAt");
+    if (daemonId === undefined ||
+        origin === undefined ||
+        token === undefined ||
+        registeredAt === undefined)
+        return undefined;
+    return { daemonId, origin, token, registeredAt };
+}

package/dist/src/phone/qr-data.d.ts

@@ -0,0 +1,8 @@
+export declare function qrVersion(byteCount: number): number;
+export declare function qrDataCodewords(bytes: Uint8Array, version: number): number[];
+export declare function qrCorrection(data: readonly number[], degree: number): number[];
+export interface QrCodewords {
+    readonly version: number;
+    readonly codewords: readonly number[];
+}
+export declare function qrCodewords(text: string): QrCodewords;