cloving 0.3.19 → 1.0.1

package/dist/src/service/gateway.js

@@ -0,0 +1,120 @@
+import { invalidCommand, serializable, textList, unserializable, } from "../broker/actor/authority-receipts.js";
+import { record } from "../protocol.js";
+export const workerCommandBound = 1_000;
+const permitted = {
+    operator: [
+        "admit-run",
+        "decide-gate",
+        "pause-run",
+        "resume-run",
+        "cancel-run",
+    ],
+    worker: [
+        "mark-started",
+        "open-gate",
+        "register-wait",
+        "report-observation",
+        "complete-run",
+        "fail-run",
+        "request-effect",
+        "report-effect",
+    ],
+    controller: ["expire-gate", "expire-lease"],
+};
+const pinned = ["decide-gate", "resume-run"];
+function denied(principal, subject) {
+    return {
+        kind: "rejected",
+        reason: "permission-denied",
+        detail: `${principal} cannot send ${subject}`,
+    };
+}
+function checked(principal, copy) {
+    const command = record(copy["command"]);
+    const documents = textList(copy["documents"]);
+    const epoch = copy["epoch"];
+    if (command === undefined || documents === undefined)
+        return undefined;
+    if (epoch === undefined)
+        return { principal, command, documents };
+    if (typeof epoch !== "number")
+        return undefined;
+    return { principal, command, documents, epoch };
+}
+function busy(bound) {
+    return {
+        kind: "rejected",
+        reason: "service-busy",
+        detail: `The service has ${String(bound)} worker commands in work. Send the command again with the same command ID.`,
+    };
+}
+function refusal(submission, textBytes) {
+    const { principal, command } = submission;
+    const kind = String(command["kind"]);
+    if (!permitted[principal].includes(kind))
+        return denied(principal, kind);
+    if (kind === "open-gate" && command["gateKind"] === undefined)
+        return denied(principal, "an untyped gate");
+    const long = submission.documents.some((document) => Buffer.byteLength(document) > textBytes);
+    if (principal === "worker" && long)
+        return {
+            kind: "rejected",
+            reason: "input-too-large",
+            detail: `A text of a worker has at most ${String(textBytes)} bytes.`,
+        };
+    return undefined;
+}
+export function commandGateway(parts) {
+    const { authority, registry, clock, textBytes } = parts;
+    const bound = parts.pendingWorkerCommands ?? workerCommandBound;
+    let pending = 0;
+    async function manifest(command) {
+        const kind = String(command["kind"]);
+        if (kind === "admit-run")
+            return registry.byPin(String(command["workflow"]))?.manifest;
+        if (!pinned.includes(kind))
+            return undefined;
+        const run = (await authority.state()).runs[String(command["runId"])];
+        return registry.byPin(run?.workflow ?? "")?.manifest;
+    }
+    async function forwarded(submission) {
+        const available = await manifest(submission.command);
+        return authority.execute(submission.command, {
+            recordedAt: clock(),
+            ...(available === undefined ? {} : { manifest: available }),
+            ...(submission.epoch === undefined ? {} : { epoch: submission.epoch }),
+            documents: submission.documents,
+        });
+    }
+    async function counted(submission) {
+        if (pending >= bound)
+            return busy(bound);
+        pending += 1;
+        try {
+            return await forwarded(submission);
+        }
+        finally {
+            pending -= 1;
+        }
+    }
+    return {
+        execute: async (given) => {
+            const copy = serializable({
+                command: given.command,
+                documents: given.documents ?? [],
+                ...(given.epoch === undefined ? {} : { epoch: given.epoch }),
+            });
+            if (copy === undefined)
+                return unserializable;
+            const submission = checked(given.principal, copy);
+            if (submission === undefined)
+                return invalidCommand;
+            const refused = refusal(submission, textBytes);
+            if (refused !== undefined)
+                return refused;
+            return submission.principal === "worker"
+                ? counted(submission)
+                : forwarded(submission);
+        },
+    };
+}

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

@@ -0,0 +1,40 @@
+import type { SubmissionContract } from "../submission.ts";
+import type { ExecutionManifest } from "../workflow-admission.ts";
+export type Resolution = {
+    readonly kind: "resolved";
+    readonly input: unknown;
+} | {
+    readonly kind: "rejected";
+    readonly code: string;
+    readonly detail: string;
+};
+export interface ResolutionRequest {
+    readonly workflowId: string;
+    readonly submission: Readonly<Record<string, unknown>>;
+    readonly commandId: string;
+    readonly signal: AbortSignal;
+}
+export interface Resolver {
+    readonly id: string;
+    readonly version: string;
+    readonly resolve: (request: ResolutionRequest) => Promise<Resolution>;
+}
+export interface WorkflowRegistration {
+    readonly workflowId: string;
+    readonly manifest: ExecutionManifest;
+    readonly availability: "available" | "unavailable";
+    readonly submission: SubmissionContract;
+    readonly resolver: Resolver;
+    readonly effectLimit?: number;
+    readonly admission?: "when-idle";
+}
+export interface Registered extends WorkflowRegistration {
+    readonly pin: string;
+}
+export interface Registry {
+    readonly workflowIds: readonly string[];
+    readonly byId: (workflowId: string) => Registered | undefined;
+    readonly byPin: (pin: string) => Registered | undefined;
+    readonly available: (pinned: ExecutionManifest) => ExecutionManifest | undefined;
+}
+export declare function workflowRegistry(workflows: readonly WorkflowRegistration[]): Registry;

package/dist/src/service/registry.js

@@ -0,0 +1,13 @@
+import { workflowPin } from "../broker/workflow-pin.js";
+export function workflowRegistry(workflows) {
+    const registered = workflows.map((workflow) => ({
+        ...workflow,
+        pin: workflowPin(workflow.manifest),
+    }));
+    return {
+        workflowIds: registered.map((workflow) => workflow.workflowId),
+        byId: (workflowId) => registered.find((workflow) => workflow.workflowId === workflowId),
+        byPin: (pin) => registered.find((workflow) => workflow.pin === pin),
+        available: (pinned) => registered.find((workflow) => workflow.manifest.workflowId === pinned.workflowId)?.manifest,
+    };
+}

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

@@ -0,0 +1,26 @@
+import type { Authority, CommandRecord, StoreReceipt } from "../broker/actor/authority.ts";
+import type { Fields, Reply } from "../protocol.ts";
+import type { ChangeSignal } from "./changes.ts";
+import type { Gateway } from "./gateway.ts";
+import type { Registry } from "./registry.ts";
+export interface ServiceContext {
+    readonly authority: Authority;
+    readonly registry: Registry;
+    readonly gateway: Gateway;
+    readonly clock: () => string;
+    readonly livenessMilliseconds: number;
+    readonly followMilliseconds: number;
+    readonly resolverMilliseconds: number;
+    readonly textBytes: number;
+    readonly documentBytes: number;
+    readonly worldReports?: () => readonly unknown[];
+    readonly changed?: ChangeSignal["next"];
+}
+export declare function result(kind: string, fields: Fields): Reply;
+export declare function failed(code: string, extra: Fields): Reply;
+export declare function invalidRequest(detail: string): Reply;
+export declare function rejection(receipt: StoreReceipt, identity: Fields): Reply;
+export declare function committed(receipt: StoreReceipt): boolean;
+export declare function isIdentifier(value: unknown): value is string;
+export declare function wholeNumber(value: unknown, minimum: number): value is number;
+export declare function publicReceipt(record: CommandRecord): Fields;

package/dist/src/service/replies.js

@@ -0,0 +1,56 @@
+import { isRecordKey } from "../authority/commands.js";
+const codes = {
+    "invalid-command": "invalid-request",
+    "request-too-large": "input-too-large",
+    "missing-document": "invalid-request",
+    "unknown-gate": "unknown-decision",
+    "missing-manifest": "workflow-unavailable",
+};
+export function result(kind, fields) {
+    return { kind: "result", result: { schemaVersion: 1, kind, ...fields } };
+}
+export function failed(code, extra) {
+    const detail = extra["detail"];
+    return {
+        kind: "error",
+        error: {
+            ...extra,
+            code,
+            detail: typeof detail === "string" ? detail : code,
+        },
+    };
+}
+export function invalidRequest(detail) {
+    return failed("invalid-request", { detail });
+}
+export function rejection(receipt, identity) {
+    if (receipt.kind === "failed")
+        return failed("authority-unavailable", {
+            ...identity,
+            detail: `${receipt.reason}: ${receipt.detail}`,
+        });
+    if (receipt.kind !== "rejected")
+        return failed("invalid-request", identity);
+    return failed(codes[receipt.reason] ?? receipt.reason, {
+        ...identity,
+        detail: receipt.detail ?? receipt.reason,
+    });
+}
+export function committed(receipt) {
+    return receipt.kind === "accepted" || receipt.kind === "duplicate";
+}
+export function isIdentifier(value) {
+    return isRecordKey(value);
+}
+export function wholeNumber(value, minimum) {
+    return (typeof value === "number" && Number.isSafeInteger(value) && value >= minimum);
+}
+export function publicReceipt(record) {
+    return {
+        commandId: record.commandId,
+        sequence: record.sequence,
+        runId: record.runId,
+        recordedAt: record.recordedAt,
+        commandDigest: record.commandDigest,
+    };
+}

package/dist/src/service/run-handlers.d.ts

@@ -0,0 +1,4 @@
+import { type Fields, type Reply } from "../protocol.ts";
+import { type ServiceContext } from "./replies.ts";
+export declare function status(context: ServiceContext, parameters: Fields): Promise<Reply>;
+export declare function runCommand(context: ServiceContext, parameters: Fields): Promise<Reply>;

package/dist/src/service/run-handlers.js

@@ -0,0 +1,271 @@
+import { runView, unresolvedEffects, } from "../authority/status.js";
+import { record } from "../protocol.js";
+import { committed, failed, invalidRequest, isIdentifier, publicReceipt, rejection, result, wholeNumber, } from "./replies.js";
+import { feedbackOf } from "./decision-handler.js";
+async function snapshot(context) {
+    const { authority } = context;
+    const state = await authority.state();
+    const sequences = await authority.queries.sequences();
+    return {
+        state,
+        operations: await authority.operations(),
+        sequences: sequences.runs,
+        times: sequences.times,
+        workflowIds: await authority.queries.workflowIds(),
+    };
+}
+function silent(context, signs) {
+    const times = signs
+        .filter((sign) => sign !== undefined)
+        .map((sign) => Date.parse(sign));
+    if (times.length === 0)
+        return false;
+    const elapsed = Date.parse(context.clock()) - Math.max(...times);
+    return elapsed > context.livenessMilliseconds;
+}
+function summaries(snapshot, runId) {
+    return snapshot.operations
+        .filter((operation) => operation.runId === runId)
+        .map((operation) => ({
+        operationId: operation.operationId,
+        kind: operation.kind,
+        releasedSequence: operation.releasedSequence,
+        outcomes: operation.deliveries.map((delivery) => delivery.outcome),
+    }));
+}
+async function effectInput(context, runId) {
+    const { effects } = context.authority;
+    const budget = await effects.budget(runId);
+    const stored = await effects.operations(runId);
+    return {
+        budget: budget === undefined
+            ? null
+            : { limit: budget.limit, spent: budget.spent },
+        effects: stored.map((operation) => ({
+            operationId: operation.operationId,
+            status: operation.status,
+            reason: operation.waitCause ?? operation.reason,
+            leaseGeneration: operation.leaseGeneration,
+            attempts: operation.attempts,
+            limit: operation.recoveryLimit,
+        })),
+        effectEvidence: await effects.evidence(runId),
+    };
+}
+async function viewOf(context, scope) {
+    const { state, sequences, times } = scope.snapshot;
+    const run = isIdentifier(scope.runId) ? state.runs[scope.runId] : undefined;
+    if (run === undefined)
+        return undefined;
+    const details = state.details[run.runId];
+    const input = {
+        ...(await effectInput(context, run.runId)),
+        closure: run.status === "cancelled"
+            ? await context.authority.effects.closure(run.runId)
+            : null,
+        run,
+        details,
+        gates: Object.values(state.gates)
+            .filter((gate) => gate.runId === run.runId)
+            .sort((left, right) => left.openedSequence - right.openedSequence),
+        operations: summaries(scope.snapshot, run.runId),
+        latestSequence: sequences[run.runId] ?? 0,
+        silent: silent(context, [
+            details?.observation?.recordedAt,
+            times[run.runId],
+        ]),
+    };
+    return {
+        ...runView(input),
+        workflowId: scope.snapshot.workflowIds[run.runId] ?? run.workflow,
+        latestAt: times[run.runId] ?? null,
+        unresolvedEffects: unresolvedEffects(input),
+        feedback: await feedbackOf(context, { state, runId: run.runId }),
+    };
+}
+function summary(view) {
+    return {
+        runId: view.runId,
+        workflowId: view.workflowId,
+        state: view.state,
+        condition: view.condition,
+        revision: view.revision,
+        latestSequence: view.latestSequence,
+        latestAt: view.latestAt,
+        pendingDecisions: view.pendingDecisions,
+    };
+}
+function costOf(text) {
+    try {
+        const cost = record(JSON.parse(text ?? "null"))?.["costUsd"];
+        return typeof cost === "number" ? cost : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+async function claudeCost(context, runId) {
+    const { effects, queries } = context.authority;
+    const digests = (await effects.operations(runId))
+        .filter((operation) => operation.capability === "claude")
+        .map((operation) => operation.result)
+        .filter((digest) => digest !== null);
+    let total = 0;
+    for (const digest of digests)
+        total += costOf(await queries.document(digest));
+    return Math.round(total * 100) / 100;
+}
+function full(view) {
+    return {
+        ...summary(view),
+        reason: view.reason,
+        evidence: view.evidence,
+        lastConfirmedObservation: view.lastConfirmedObservation,
+        recovery: view.recovery,
+        claudeCostUsd: view.claudeCostUsd,
+        budget: view.budget,
+        effects: view.effects,
+        nextAction: view.nextAction,
+        nextActionAt: view.nextActionAt,
+        humanInputCanHelp: view.humanInputCanHelp,
+        feedback: view.feedback,
+    };
+}
+async function outcomeOf(context, view) {
+    if (view.state !== "completed")
+        return null;
+    const event = await context.authority.queries.latestCompletion({
+        runId: view.runId,
+        atOrBefore: view.latestSequence,
+    });
+    const kind = event?.payload["outcome"];
+    if (kind === undefined)
+        return null;
+    return { kind, reason: event?.payload["outcomeReason"] ?? null };
+}
+function titleOf(input, workflowId) {
+    const ticket = input?.["ticket"];
+    if (typeof ticket !== "string")
+        return null;
+    const fallback = `Cloving task ${String(input?.["cycleId"])}`;
+    const lines = ticket.split("\n");
+    if (workflowId === "develop-prompt") {
+        const first = lines.find((line) => /\S/.test(line));
+        return first === undefined
+            ? fallback
+            : first.replace(/^# /, "").trim().slice(0, 200);
+    }
+    const first = lines[0] ?? "";
+    return first.startsWith("# ")
+        ? first.slice(2).trim().slice(0, 200)
+        : fallback;
+}
+async function metadataOf(context, source) {
+    const document = source.digest
+        ? await context.authority.queries.document(source.digest)
+        : undefined;
+    const input = record(JSON.parse(document ?? "null"));
+    const ticketId = input?.["ticketId"];
+    return {
+        ticketId: typeof ticketId === "string" && ticketId !== "" ? ticketId : null,
+        title: titleOf(input, source.workflowId),
+    };
+}
+async function listed(context, page) {
+    const identifiers = Object.keys(page.snapshot.state.runs)
+        .sort()
+        .filter((runId) => runId > page.after);
+    const shown = identifiers.slice(0, page.limit);
+    const views = [];
+    for (const runId of shown)
+        views.push(await viewOf(context, { snapshot: page.snapshot, runId }));
+    const runs = views.filter((view) => view !== undefined).map(summary);
+    return result("run-list", {
+        workflows: context.registry.workflowIds,
+        runs,
+        next: identifiers.length > shown.length ? (shown.at(-1) ?? null) : null,
+        worldReports: context.worldReports?.() ?? [],
+    });
+}
+export async function status(context, parameters) {
+    const { runId } = parameters;
+    const after = parameters["after"] ?? "";
+    const limit = parameters["limit"] ?? 50;
+    if (typeof after !== "string" || !wholeNumber(limit, 1) || limit > 500)
+        return invalidRequest("The status request is not valid.");
+    const current = await snapshot(context);
+    if (runId === undefined)
+        return listed(context, { snapshot: current, after, limit });
+    const named = typeof runId === "string" ? runId : "";
+    const view = await viewOf(context, { snapshot: current, runId: named });
+    if (view === undefined)
+        return failed("unknown-run", { detail: `No run has the ID ${named}.` });
+    const claudeCostUsd = await claudeCost(context, view.runId);
+    return result("run-status", {
+        run: {
+            ...full({ ...view, claudeCostUsd }),
+            outcome: await outcomeOf(context, view),
+            ...(await metadataOf(context, {
+                workflowId: view.workflowId,
+                digest: current.state.details[view.runId]?.input,
+            })),
+        },
+    });
+}
+const kinds = {
+    pause: "pause-run",
+    resume: "resume-run",
+    drop: "cancel-run",
+};
+async function reported(context, outcome) {
+    const { command, commandId, runId } = outcome;
+    const stored = await context.authority.queries.receipt(commandId);
+    const current = await snapshot(context);
+    const view = await viewOf(context, { snapshot: current, runId });
+    if (stored === undefined || view === undefined)
+        return failed("authority-unavailable", { commandId, runId });
+    const operations = current.operations.filter((operation) => operation.runId === runId);
+    return result("run-command", {
+        command,
+        runId,
+        commandId,
+        replayed: outcome.replayed,
+        receipt: publicReceipt(stored),
+        committed: {
+            state: view.state,
+            revision: view.revision,
+            revokedIntents: operations.filter((operation) => operation.releasedSequence === stored.sequence).length,
+        },
+        observed: {
+            condition: view.condition,
+            unresolvedEffects: view.unresolvedEffects,
+        },
+    });
+}
+export async function runCommand(context, parameters) {
+    const { command, runId, expectedRevision, commandId } = parameters;
+    if (typeof command !== "string" ||
+        !Object.hasOwn(kinds, command) ||
+        !isIdentifier(runId) ||
+        !isIdentifier(commandId) ||
+        !wholeNumber(expectedRevision, 1))
+        return invalidRequest("The run command request is not valid.");
+    const receipt = await context.gateway.execute({
+        principal: "operator",
+        command: { kind: kinds[command], commandId, runId, expectedRevision },
+    });
+    if (!committed(receipt)) {
+        const run = (await context.authority.state()).runs[runId];
+        return rejection(receipt, {
+            commandId,
+            runId,
+            currentRevision: run?.revision ?? null,
+        });
+    }
+    return reported(context, {
+        command,
+        commandId,
+        runId,
+        replayed: receipt.kind === "duplicate",
+    });
+}

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

@@ -0,0 +1,58 @@
+import { type Authority, type AuthorityTiming, type Delivery, type EffectSettings, type Refusal } from "../broker/actor/authority.ts";
+import { type WorkflowRegistration } from "./registry.ts";
+import { type WorkerPort } from "./worker-port.ts";
+export type { WorkflowRegistration } from "./registry.ts";
+export type { EffectReply, EffectReport, EffectRequest, WorkerPort, } from "./worker-port.ts";
+export interface ServiceTiming {
+    readonly authority: AuthorityTiming;
+    readonly expiryScanMilliseconds: number;
+    readonly livenessMilliseconds: number;
+    readonly followMilliseconds: number;
+    readonly resolverMilliseconds: number;
+    readonly idleMilliseconds: number;
+}
+export declare const serviceTiming: ServiceTiming;
+export interface ServiceLimits {
+    readonly textBytes: number;
+    readonly documentBytes: number;
+    readonly pendingWorkerCommands: number;
+}
+export declare const serviceLimits: ServiceLimits;
+export interface ServiceHost {
+    readonly close: () => Promise<void>;
+    readonly reports?: () => readonly unknown[];
+}
+export interface HostPorts {
+    readonly state: Authority["state"];
+    readonly submit: WorkerPort["submit"];
+    readonly input: (runId: string) => Promise<string | undefined>;
+    readonly document: (digest: string) => Promise<string | undefined>;
+    readonly workflowId: (runId: string) => Promise<string | undefined>;
+    readonly requestEffect: WorkerPort["requestEffect"];
+    readonly operation: Authority["effects"]["operation"];
+    readonly reportEffect: WorkerPort["reportEffect"];
+    readonly openGate: WorkerPort["openGate"];
+    readonly registerWait: WorkerPort["registerWait"];
+}
+export interface ServiceOptions {
+    readonly stateDirectory: string;
+    readonly runtimeDirectory: string;
+    readonly workflows: readonly WorkflowRegistration[];
+    readonly delivery: Delivery;
+    readonly host?: (ports: HostPorts) => Promise<ServiceHost>;
+    readonly timing?: ServiceTiming;
+    readonly limits?: ServiceLimits;
+    readonly effects?: Partial<EffectSettings>;
+    readonly clock?: () => string;
+}
+export interface Service {
+    readonly socket: string;
+    readonly epoch: number;
+    readonly worker: WorkerPort;
+    readonly close: () => Promise<void>;
+}
+export type ServiceOpening = {
+    readonly kind: "started";
+    readonly service: Service;
+} | Refusal;
+export declare function startService(options: ServiceOptions): Promise<ServiceOpening>;