cloving 0.3.20 → 1.1.0

package/dist/src/service/submission-handler.js

@@ -0,0 +1,206 @@
+import { createHash } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
+import { isIdentifier as isWorkflowIdentifier } from "../authority/commands.js";
+import { documentDigest } from "../broker/decision-restore.js";
+import { record } from "../protocol.js";
+import { checkResolution, checkSubmission, normalizedRequest, } from "../submission.js";
+import { committed, failed, invalidRequest, isIdentifier, publicReceipt, rejection, result, } from "./replies.js";
+export function runIdentity(commandId) {
+    return `run-${createHash("sha256").update(commandId).digest("hex").slice(0, 32)}`;
+}
+function resolverIdentity(text) {
+    const separator = text.lastIndexOf(":");
+    return { id: text.slice(0, separator), version: text.slice(separator + 1) };
+}
+function admitted(stored, outcome) {
+    const { command } = stored;
+    return result("run-admitted", {
+        runId: stored.runId,
+        workflowId: outcome.workflowId,
+        commandId: stored.commandId,
+        replayed: outcome.replayed,
+        receipt: publicReceipt(stored),
+        binding: {
+            workflowPin: command.workflow,
+            resolver: resolverIdentity(String(command.resolver)),
+            requestDigest: command.submission,
+            executionInputDigest: command.input,
+        },
+    });
+}
+function conflict(commandId) {
+    return failed("conflicting-command", {
+        commandId,
+        detail: "The command ID is known with a different request.",
+    });
+}
+function replayed(existing, request) {
+    const submission = record(request.submission);
+    const same = existing.command.kind === "admit-run" &&
+        submission !== undefined &&
+        documentDigest(normalizedRequest(request.workflowId, submission)) ===
+            existing.command.submission;
+    return same
+        ? admitted(existing, { workflowId: request.workflowId, replayed: true })
+        : conflict(existing.commandId);
+}
+function effectBudget(workflow) {
+    if (workflow.effectLimit === undefined)
+        return {};
+    return {
+        effectLimit: workflow.effectLimit,
+        capabilities: JSON.stringify([...workflow.manifest.capabilities].sort()),
+    };
+}
+function usable(workflow, workflowId) {
+    if (workflow === undefined)
+        return {
+            kind: "unusable",
+            reply: failed("unknown-workflow", {
+                detail: `No admitted workflow has the ID ${workflowId}.`,
+            }),
+        };
+    if (workflow.availability !== "available")
+        return {
+            kind: "unusable",
+            reply: failed("workflow-unavailable", {
+                detail: `The workflow ${workflowId} is not available. A required capability did not pass admission.`,
+            }),
+        };
+    return { kind: "usable", workflow };
+}
+async function resolved(context, admission) {
+    const { workflow, workflowId, commandId, submission } = admission;
+    const limit = new AbortController();
+    const timer = new AbortController();
+    const request = { workflowId, submission, commandId, signal: limit.signal };
+    const call = Promise.resolve(request)
+        .then((given) => workflow.resolver.resolve(given))
+        .then((value) => checkResolution(value) ?? "failure")
+        .catch(() => "failure");
+    const expired = delay(context.resolverMilliseconds, "timeout", {
+        signal: timer.signal,
+    });
+    try {
+        const outcome = await Promise.race([call, expired]);
+        if (outcome === "timeout")
+            limit.abort();
+        return outcome;
+    }
+    finally {
+        timer.abort();
+    }
+}
+function unresolved(context, outcome) {
+    const { kind, commandId } = outcome;
+    if (kind === "timeout")
+        return failed("resolver-timeout", {
+            commandId,
+            detail: `The resolver gave no result in ${String(context.resolverMilliseconds)} ms. Send the command again with the same command ID.`,
+        });
+    return failed("resolver-failure", {
+        commandId,
+        detail: "The resolver of the workflow failed or gave a result that is not valid. Nothing is admitted.",
+    });
+}
+async function admit(context, admission) {
+    const { workflow, workflowId, commandId, normalized } = admission;
+    const resolution = await resolved(context, admission);
+    if (typeof resolution === "string")
+        return unresolved(context, { kind: resolution, commandId });
+    if (resolution.kind === "rejected")
+        return failed(resolution.code, { commandId, detail: resolution.detail });
+    const { input } = resolution;
+    if (Buffer.byteLength(input) > context.documentBytes)
+        return unresolved(context, { kind: "failure", commandId });
+    const receipt = await context.gateway.execute({
+        principal: "operator",
+        command: {
+            kind: "admit-run",
+            commandId,
+            runId: runIdentity(commandId),
+            workflow: workflow.pin,
+            submission: documentDigest(normalized),
+            input: documentDigest(input),
+            resolver: `${workflow.resolver.id}:${workflow.resolver.version}`,
+            ...effectBudget(workflow),
+        },
+        documents: [normalized, input],
+    });
+    if (!committed(receipt))
+        return rejection(receipt, { commandId });
+    const stored = await context.authority.queries.receipt(commandId);
+    if (stored === undefined)
+        return conflict(commandId);
+    return admitted(stored, {
+        workflowId,
+        replayed: receipt.kind === "duplicate",
+    });
+}
+async function submitted(context, parameters) {
+    const { workflowId, commandId } = parameters;
+    if (!isWorkflowIdentifier(workflowId) || !isIdentifier(commandId))
+        return invalidRequest("The workflow ID or the command ID is not valid.");
+    const existing = await context.authority.queries.receipt(commandId);
+    if (existing !== undefined)
+        return replayed(existing, {
+            workflowId,
+            submission: parameters["submission"],
+        });
+    const found = usable(context.registry.byId(workflowId), workflowId);
+    if (found.kind === "unusable")
+        return found.reply;
+    const contract = found.workflow.submission;
+    const check = checkSubmission({
+        ...contract,
+        maximumBytes: Math.min(contract.maximumBytes, context.documentBytes),
+    }, {
+        workflowId,
+        submission: parameters["submission"],
+        source: parameters["source"],
+    });
+    if (check.kind === "rejected")
+        return failed(check.code, { commandId, detail: check.detail });
+    if (found.workflow.admission === "when-idle" &&
+        (await activeWorkflow(context, workflowId)))
+        return failed("workflow-active", {
+            commandId,
+            detail: `The workflow ${workflowId} already has an active run.`,
+        });
+    return admit(context, {
+        workflow: found.workflow,
+        workflowId,
+        commandId,
+        submission: check.submission,
+        normalized: check.normalized,
+    });
+}
+async function activeWorkflow(context, workflowId) {
+    const workflows = await context.authority.queries.workflowIds();
+    const state = await context.authority.state();
+    return Object.values(state.runs).some((run) => workflows[run.runId] === workflowId &&
+        !["completed", "failed", "cancelled"].includes(run.status));
+}
+export function submissionHandler(context) {
+    const pending = new Map();
+    return (parameters) => {
+        const keys = [`command:${String(parameters["commandId"])}`];
+        const workflowId = String(parameters["workflowId"]);
+        if (context.registry.byId(workflowId)?.admission === "when-idle")
+            keys.push(`workflow:${workflowId}`);
+        const next = () => submitted(context, parameters);
+        const previous = keys
+            .map((key) => pending.get(key))
+            .filter((reply) => reply !== undefined);
+        const reply = Promise.allSettled(previous).then(next);
+        for (const key of keys)
+            pending.set(key, reply);
+        const settled = () => {
+            for (const key of keys)
+                if (pending.get(key) === reply)
+                    pending.delete(key);
+        };
+        reply.then(settled, settled);
+        return reply;
+    };
+}

package/dist/src/service/transport.d.ts

@@ -0,0 +1,16 @@
+import { type Reply, type ServiceRequest } from "../protocol.ts";
+import type { Connection } from "./event-handler.ts";
+export type Handle = (request: ServiceRequest, connection: Connection) => Promise<Reply | undefined>;
+export interface Listener {
+    readonly close: () => Promise<void>;
+}
+export interface ConnectionLimits {
+    readonly idleMilliseconds: number;
+}
+export declare const connectionLimits: ConnectionLimits;
+export declare function listen(options: {
+    readonly path: string;
+    readonly handle: Handle;
+    readonly limits?: ConnectionLimits;
+}): Promise<Listener>;
+export declare function reachable(path: string): Promise<boolean>;

package/dist/src/service/transport.js

@@ -0,0 +1,141 @@
+import { chmod, rm } from "node:fs/promises";
+import net from "node:net";
+import { eventLine, maximumFrameBytes, parseRequest, replyLine, } from "../protocol.js";
+function tooLarge() {
+    return {
+        kind: "error",
+        error: {
+            code: "request-too-large",
+            detail: `A request has at most ${String(maximumFrameBytes)} bytes.`,
+        },
+    };
+}
+function unavailable(error) {
+    return {
+        kind: "error",
+        error: {
+            code: "authority-unavailable",
+            detail: String(Reflect.get(Object(error), "message")),
+        },
+    };
+}
+function flushed(socket, limit) {
+    return new Promise((settle) => {
+        const settled = (outcome) => () => {
+            clearTimeout(timer);
+            socket.off("drain", onDrain);
+            socket.off("close", onStall);
+            if (outcome === "stalled")
+                socket.destroy();
+            settle(outcome === "drained");
+        };
+        const onDrain = settled("drained");
+        const onStall = settled("stalled");
+        const timer = setTimeout(onStall, limit);
+        socket.once("drain", onDrain);
+        socket.once("close", onStall);
+    });
+}
+function served(socket, serving) {
+    const { handle, limits } = serving;
+    let buffered = "";
+    let handled = false;
+    const connection = {
+        send: (events) => {
+            if (socket.destroyed)
+                return Promise.resolve(false);
+            const written = events.map((event) => socket.write(eventLine(event)));
+            return written.includes(false)
+                ? flushed(socket, limits.idleMilliseconds)
+                : Promise.resolve(true);
+        },
+        closed: () => socket.destroyed || socket.readableEnded,
+    };
+    socket.setTimeout(limits.idleMilliseconds, () => {
+        if (!handled)
+            socket.destroy();
+    });
+    const finish = (reply) => {
+        if (socket.destroyed)
+            return;
+        if (reply === undefined)
+            socket.destroy();
+        else
+            socket.end(replyLine(reply));
+        setTimeout(() => socket.destroy(), limits.idleMilliseconds).unref();
+    };
+    socket.setEncoding("utf8");
+    socket.on("error", () => undefined);
+    socket.on("data", (data) => {
+        if (handled)
+            return;
+        buffered += data;
+        const end = buffered.indexOf("\n");
+        if (end < 0 && Buffer.byteLength(buffered) <= maximumFrameBytes)
+            return;
+        handled = true;
+        if (end < 0 || end > maximumFrameBytes) {
+            finish(tooLarge());
+            return;
+        }
+        const parsed = parseRequest(buffered.slice(0, end));
+        if (parsed.kind === "error") {
+            finish(parsed);
+            return;
+        }
+        Promise.resolve(parsed.request)
+            .then((request) => handle(request, connection))
+            .then(finish, (error) => {
+            finish(unavailable(error));
+        });
+    });
+    socket.on("end", () => {
+        if (!handled)
+            socket.end();
+    });
+}
+export const connectionLimits = {
+    idleMilliseconds: 30_000,
+};
+export async function listen(options) {
+    const { path, handle } = options;
+    const limits = options.limits ?? connectionLimits;
+    const sockets = new Set();
+    const server = net.createServer({ allowHalfOpen: true }, (socket) => {
+        sockets.add(socket);
+        socket.on("close", () => sockets.delete(socket));
+        served(socket, { handle, limits });
+    });
+    await new Promise((ready, refuse) => {
+        server.once("error", refuse);
+        server.listen(path, () => {
+            server.off("error", refuse);
+            ready();
+        });
+    });
+    await chmod(path, 0o600);
+    return {
+        close: async () => {
+            for (const socket of sockets)
+                socket.destroy();
+            await new Promise((closed) => {
+                server.close(() => {
+                    closed();
+                });
+            });
+            await rm(path, { force: true });
+        },
+    };
+}
+export function reachable(path) {
+    return new Promise((settle) => {
+        const socket = net.connect(path);
+        socket.on("connect", () => {
+            socket.destroy();
+            settle(true);
+        });
+        socket.on("error", () => {
+            settle(false);
+        });
+    });
+}

package/dist/src/service/worker-port.d.ts

@@ -0,0 +1,85 @@
+import type { Authority, OperationView, StoreReceipt, StoredDisposition } from "../broker/actor/authority.ts";
+import type { Command, Gateway } from "./gateway.ts";
+interface Identified {
+    readonly runId: string;
+    readonly commandId: string;
+}
+interface Revised extends Identified {
+    readonly expectedRevision: number;
+}
+export interface GateOpening extends Revised {
+    readonly gateId: string;
+    readonly kind: "question" | "approval";
+    readonly prompt: string;
+    readonly subject: string;
+    readonly expiresAt?: string;
+}
+export interface WaitRegistration extends Identified {
+    readonly gateId: string;
+}
+export interface ObservationReport extends Identified {
+    readonly condition: string;
+    readonly reason: string;
+    readonly evidence?: string;
+    readonly retryAt?: string;
+    readonly operationId?: string;
+    readonly attempt?: number;
+    readonly limit?: number;
+}
+export interface EffectScope {
+    readonly phase: string;
+    readonly operation: string;
+    readonly round: number;
+    readonly key?: string;
+    readonly stage?: {
+        readonly id: string;
+        readonly visit: string;
+        readonly branch: string;
+    };
+}
+export interface EffectRequest extends Identified {
+    readonly scope: EffectScope;
+    readonly capability: string;
+    readonly method: string;
+    readonly target: string;
+    readonly payload: string;
+    readonly units: number;
+    readonly resource?: string;
+    readonly transport?: string;
+    readonly source?: string;
+    readonly sourceGeneration?: number;
+    readonly epoch?: number;
+}
+export interface EffectReport extends Identified {
+    readonly operationId: string;
+    readonly inputDigest: string;
+    readonly leaseGeneration: number;
+    readonly worker: string;
+    readonly outcome: "completed" | "failed" | "stopped";
+    readonly result?: string;
+    readonly reason?: string;
+    readonly evidence?: string;
+    readonly epoch?: number;
+}
+export interface EffectReply {
+    readonly receipt: StoreReceipt;
+    readonly disposition: StoredDisposition | null;
+    readonly operation: OperationView | null;
+}
+export interface WorkerPort {
+    readonly submit: (command: Command, documents?: readonly string[]) => Promise<StoreReceipt>;
+    readonly started: (run: Revised) => Promise<StoreReceipt>;
+    readonly openGate: (opening: GateOpening) => Promise<StoreReceipt>;
+    readonly registerWait: (wait: WaitRegistration) => Promise<StoreReceipt>;
+    readonly observe: (report: ObservationReport) => Promise<StoreReceipt>;
+    readonly completed: (run: Revised) => Promise<StoreReceipt>;
+    readonly failed: (run: Revised) => Promise<StoreReceipt>;
+    readonly requestEffect: (request: EffectRequest) => Promise<EffectReply>;
+    readonly reportEffect: (report: EffectReport) => Promise<EffectReply>;
+}
+interface Parts {
+    readonly gateway: Gateway;
+    readonly authority: Authority;
+}
+export declare function workerPort(parts: Parts): WorkerPort;
+export {};

package/dist/src/service/worker-port.js

@@ -0,0 +1,126 @@
+import { documentDigest } from "../broker/decision-restore.js";
+import { effectInputDigest } from "../broker/effect-restore.js";
+import { operationIdentity } from "../operation-identity.js";
+function reference(text) {
+    return typeof text === "string" ? documentDigest(text) : null;
+}
+function sequenceOf(receipt) {
+    const committed = receipt.kind === "accepted" || receipt.kind === "duplicate";
+    return committed ? receipt.sequence : undefined;
+}
+async function stored(authority, answer) {
+    const { receipt, operationId } = answer;
+    if (receipt.kind === "failed")
+        return { receipt, disposition: null, operation: null };
+    const sequence = sequenceOf(receipt);
+    try {
+        const disposition = sequence === undefined
+            ? undefined
+            : await authority.effects.disposition(sequence);
+        return {
+            receipt,
+            disposition: disposition ?? null,
+            operation: (await authority.effects.operation(operationId)) ?? null,
+        };
+    }
+    catch {
+        return { receipt, disposition: null, operation: null };
+    }
+}
+function texts(values) {
+    return values.every((value) => typeof value === "string");
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null;
+}
+function unanswered(reason) {
+    return {
+        receipt: { kind: "rejected", reason },
+        disposition: null,
+        operation: null,
+    };
+}
+function effectPort(parts) {
+    const { gateway, authority } = parts;
+    return {
+        requestEffect: async (request) => {
+            if (!isObject(request))
+                return unanswered("invalid-command");
+            const { scope, payload, epoch, ...rest } = request;
+            if (!texts([payload, rest.capability, rest.method, rest.target]))
+                return unanswered("invalid-command");
+            const identity = operationIdentity({ ...scope, run: request.runId });
+            if (identity.kind !== "valid")
+                return unanswered(identity.reason);
+            const operationId = identity.value;
+            const digest = documentDigest(payload);
+            const receipt = await gateway.execute({
+                principal: "worker",
+                command: {
+                    kind: "request-effect",
+                    ...rest,
+                    operationId,
+                    payload: digest,
+                    inputDigest: effectInputDigest({
+                        capability: request.capability,
+                        method: request.method,
+                        target: request.target,
+                        payload: digest,
+                    }),
+                    recoveryLimit: authority.recoveryLimit,
+                },
+                documents: [payload],
+                epoch: epoch ?? authority.epoch,
+            });
+            return stored(authority, { receipt, operationId });
+        },
+        reportEffect: async (report) => {
+            if (!isObject(report))
+                return unanswered("invalid-command");
+            const { result, epoch, ...rest } = report;
+            const given = result === undefined ? [] : [result];
+            if (!texts([report.operationId, ...given]))
+                return unanswered("invalid-command");
+            const receipt = await gateway.execute({
+                principal: "worker",
+                command: {
+                    kind: "report-effect",
+                    ...rest,
+                    ...(result === undefined ? {} : { result: documentDigest(result) }),
+                },
+                documents: result === undefined ? [] : [result],
+                epoch: epoch ?? authority.epoch,
+            });
+            return stored(authority, {
+                receipt,
+                operationId: report.operationId,
+            });
+        },
+    };
+}
+export function workerPort(parts) {
+    const { gateway } = parts;
+    const submit = (command, documents) => gateway.execute({
+        principal: "worker",
+        command,
+        ...(documents === undefined ? {} : { documents }),
+    });
+    return {
+        submit,
+        started: (run) => submit({ kind: "mark-started", ...run }),
+        openGate: (opening) => {
+            const { kind, prompt, ...rest } = opening;
+            return submit({
+                kind: "open-gate",
+                ...rest,
+                gateKind: kind,
+                prompt: reference(prompt),
+            }, [prompt]);
+        },
+        registerWait: (wait) => submit({ kind: "register-wait", ...wait }),
+        observe: (report) => submit({ kind: "report-observation", ...report }),
+        completed: (run) => submit({ kind: "complete-run", ...run }),
+        failed: (run) => submit({ kind: "fail-run", ...run }),
+        ...effectPort(parts),
+    };
+}

package/dist/src/service/worker-totals.d.ts

@@ -0,0 +1,3 @@
+import { type WorkerTotals } from "../worker-usage.ts";
+import type { ServiceContext } from "./replies.ts";
+export declare function usageTotals(context: ServiceContext, runId: string): Promise<WorkerTotals>;

package/dist/src/service/worker-totals.js

@@ -0,0 +1,28 @@
+import { record } from "../protocol.js";
+import { priceOf, usageOf, workerTotals, } from "../worker-usage.js";
+function reportFields(text) {
+    try {
+        return record(JSON.parse(text ?? "null")) ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+export async function usageTotals(context, runId) {
+    const { effects, queries } = context.authority;
+    const operations = (await effects.operations(runId)).filter((operation) => operation.capability === "claude" &&
+        ["completed", "failed", "stopped", "cancelled", "refused"].includes(operation.status));
+    const turns = [];
+    for (const operation of operations) {
+        const report = reportFields(operation.result === null
+            ? undefined
+            : await queries.document(operation.result));
+        turns.push({
+            operationId: operation.operationId,
+            usage: usageOf(report["usage"]),
+            costUsd: priceOf(report["costUsd"]),
+            estimatedCostUsd: priceOf(report["estimatedCostUsd"]),
+        });
+    }
+    return workerTotals(turns);
+}

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

@@ -0,0 +1,57 @@
+export declare const stepBridgeKey = "cloving.step-bridge/v1";
+export interface ProtectedScope {
+    readonly phase: string;
+    readonly operation: string;
+    readonly round: number;
+    readonly key?: string;
+    readonly stage?: {
+        readonly id: string;
+        readonly visit: string;
+        readonly branch: string;
+    };
+}
+export interface ProtectedRequest {
+    readonly scope: ProtectedScope;
+    readonly capability: string;
+    readonly method: string;
+    readonly target: string;
+    readonly payload: string;
+    readonly units: number;
+    readonly resource?: string;
+}
+export type ProtectedResult = {
+    readonly kind: "completed";
+    readonly operationId: string;
+    readonly receipt: string | null;
+    readonly result: string | null;
+} | {
+    readonly kind: "failed" | "stopped" | "blocked" | "cancelled";
+    readonly operationId: string;
+    readonly reason: string | null;
+} | {
+    readonly kind: "refused";
+    readonly reason: string;
+} | {
+    readonly kind: "unavailable";
+    readonly reason: string;
+};
+export interface GateRequest {
+    readonly gateId: string;
+    readonly kind: "question" | "approval";
+    readonly prompt: string;
+}
+export type GateResult = {
+    readonly kind: "opened";
+    readonly decisionId: string;
+} | {
+    readonly kind: "refused";
+    readonly reason: string;
+} | {
+    readonly kind: "unavailable";
+    readonly reason: string;
+};
+export interface StepBridge {
+    readonly effect: (request: ProtectedRequest) => Promise<ProtectedResult>;
+    readonly gate: (request: GateRequest) => Promise<GateResult>;
+}
+export declare function isStepBridge(value: unknown): value is StepBridge;

package/dist/src/step-bridge.js

@@ -0,0 +1,4 @@
+export const stepBridgeKey = "cloving.step-bridge/v1";
+export function isStepBridge(value) {
+    return ["effect", "gate"].every((member) => typeof Reflect.get(Object(value), member) === "function");
+}

package/dist/src/steps/decision-gate.d.ts

@@ -0,0 +1,2 @@
+import { type GateRequest, type GateResult } from "../step-bridge.ts";
+export declare function decisionGate(request: GateRequest): Promise<GateResult>;

package/dist/src/steps/decision-gate.js

@@ -0,0 +1,8 @@
+import { isStepBridge, stepBridgeKey, } from "../step-bridge.js";
+export async function decisionGate(request) {
+    "use step";
+    const bridge = Reflect.get(globalThis, Symbol.for(stepBridgeKey));
+    if (!isStepBridge(bridge))
+        return { kind: "unavailable", reason: "cloving-host-unavailable" };
+    return await bridge.gate(request);
+}