cloving 0.3.20 → 1.1.0

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

@@ -0,0 +1,263 @@
+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 { usageTotals } from "./worker-totals.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 full(view) {
+    return {
+        ...summary(view),
+        reason: view.reason,
+        evidence: view.evidence,
+        lastConfirmedObservation: view.lastConfirmedObservation,
+        recovery: view.recovery,
+        claudeCostUsd: view.claudeCostUsd,
+        estimatedCostUsd: view.estimatedCostUsd,
+        usage: view.usage,
+        workerTurns: view.workerTurns,
+        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;
+    const ticketStatus = event?.payload["ticketStatus"];
+    return {
+        kind,
+        reason: event?.payload["outcomeReason"] ?? null,
+        ...(ticketStatus === undefined ? {} : { ticketStatus }),
+        ...(event?.payload["issueUpdate"] === "failed"
+            ? { issueUpdate: "failed" }
+            : {}),
+    };
+}
+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 totals = await usageTotals(context, view.runId);
+    return result("run-status", {
+        run: {
+            ...full({ ...view, ...totals }),
+            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>;

package/dist/src/service/service.js

@@ -0,0 +1,212 @@
+import { lstat, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { authorityTiming, openAuthority, } from "../broker/actor/authority.js";
+import { socketAddress } from "../broker/socket-address.js";
+import { changeSignal } from "./changes.js";
+import { decision, questions } from "./decision-handler.js";
+import { events } from "./event-handler.js";
+import { expiryScan } from "./expiry.js";
+import { commandGateway, workerCommandBound } from "./gateway.js";
+import { workflowRegistry, } from "./registry.js";
+import { failed } from "./replies.js";
+import { runCommand, status } from "./run-handlers.js";
+import { submissionHandler } from "./submission-handler.js";
+import { connectionLimits, listen, reachable } from "./transport.js";
+import { workerPort } from "./worker-port.js";
+export const serviceTiming = {
+    authority: authorityTiming,
+    expiryScanMilliseconds: 1_000,
+    livenessMilliseconds: 600_000,
+    followMilliseconds: 250,
+    resolverMilliseconds: 30_000,
+    idleMilliseconds: connectionLimits.idleMilliseconds,
+};
+export const serviceLimits = {
+    textBytes: 65_536,
+    documentBytes: 262_144,
+    pendingWorkerCommands: workerCommandBound,
+};
+function refused(reason, detail) {
+    return { kind: "refused", reason, detail };
+}
+async function privateDirectory(directory) {
+    const entry = await lstat(directory).catch(() => undefined);
+    if (entry === undefined || !entry.isDirectory())
+        return refused("insecure-runtime-directory", "not a directory");
+    const owned = entry.uid === process.getuid?.();
+    const mode = entry.mode & 0o777;
+    if (owned && (mode & 0o077) === 0)
+        return undefined;
+    return refused("insecure-runtime-directory", owned ? `mode ${mode.toString(8)}` : "owned by a different user");
+}
+async function endpoint(directory) {
+    const insecure = await privateDirectory(directory);
+    if (insecure !== undefined)
+        return insecure;
+    const address = socketAddress(join(directory, "control.sock"));
+    if (address.kind === "refused")
+        return address;
+    if (await reachable(address.path))
+        return refused("service-already-running", directory);
+    return address.path;
+}
+function wallClock() {
+    return new Date().toISOString();
+}
+function dispatcher(context) {
+    const run = submissionHandler(context);
+    const operations = new Map([
+        ["run", (request) => run(request.parameters)],
+        ["status", (request) => status(context, request.parameters)],
+        ["questions", (request) => questions(context, request.parameters)],
+        ["decision", (request) => decision(context, request.parameters)],
+        ["run-command", (request) => runCommand(context, request.parameters)],
+        [
+            "events",
+            (request, connection) => events(context, { parameters: request.parameters, connection }),
+        ],
+    ]);
+    return (request, connection) => {
+        const operation = operations.get(request.operation);
+        if (operation === undefined)
+            return Promise.resolve(failed("unknown-operation", {
+                detail: `The service has no operation ${request.operation}.`,
+            }));
+        return operation(request, connection);
+    };
+}
+async function started(authority, setup) {
+    const { options, path, timing, registry, gateway, host } = setup;
+    const clock = options.clock ?? wallClock;
+    const { textBytes, documentBytes } = options.limits ?? serviceLimits;
+    await rm(path, { force: true });
+    const changes = changeSignal(authority.changes.subscribe);
+    const listener = await listen({
+        path,
+        limits: { idleMilliseconds: timing.idleMilliseconds },
+        handle: dispatcher({
+            authority,
+            registry,
+            gateway,
+            clock,
+            changed: changes.next,
+            livenessMilliseconds: timing.livenessMilliseconds,
+            followMilliseconds: timing.followMilliseconds,
+            resolverMilliseconds: timing.resolverMilliseconds,
+            textBytes,
+            documentBytes,
+            worldReports: () => host?.reports?.() ?? [],
+        }),
+    });
+    const stopping = new AbortController();
+    const delivering = Promise.allSettled([authority.deliver(stopping.signal)]);
+    const expiry = expiryScan({
+        authority,
+        gateway,
+        clock,
+        intervalMilliseconds: timing.expiryScanMilliseconds,
+    });
+    return {
+        socket: path,
+        epoch: authority.epoch,
+        worker: setup.worker,
+        close: async () => {
+            changes.close();
+            await expiry.stop();
+            await listener.close();
+            stopping.abort();
+            await delivering;
+            await released(authority, host);
+        },
+    };
+}
+async function released(authority, host) {
+    try {
+        await host?.close();
+    }
+    finally {
+        await authority.close();
+    }
+}
+export async function startService(options) {
+    const path = await endpoint(options.runtimeDirectory);
+    if (typeof path !== "string")
+        return path;
+    const timing = options.timing ?? serviceTiming;
+    const registry = workflowRegistry(options.workflows);
+    const opening = await openAuthority(options.stateDirectory, {
+        delivery: options.delivery,
+        timing: timing.authority,
+        available: registry.available,
+        ...(options.effects === undefined ? {} : { effects: options.effects }),
+        ...(options.clock === undefined ? {} : { clock: options.clock }),
+    });
+    if (opening.kind === "refused")
+        return opening;
+    const { authority } = opening;
+    const gateway = serviceGateway(authority, { options, registry });
+    const worker = workerPort({ gateway, authority });
+    const host = await hosted(options, hostPorts(authority, worker));
+    if (host.kind === "refused") {
+        await authority.close();
+        return host;
+    }
+    try {
+        return {
+            kind: "started",
+            service: await started(authority, {
+                options,
+                path,
+                timing,
+                registry,
+                gateway,
+                worker,
+                host: host.host,
+            }),
+        };
+    }
+    catch (error) {
+        const unclosed = await released(authority, host.host).then(() => "", (failure) => `; the close failed: ${message(failure)}`);
+        return refused("transport-failure", `${message(error)}${unclosed}`);
+    }
+}
+function serviceGateway(authority, parts) {
+    const limits = parts.options.limits ?? serviceLimits;
+    return commandGateway({
+        authority,
+        registry: parts.registry,
+        clock: parts.options.clock ?? wallClock,
+        textBytes: limits.textBytes,
+        pendingWorkerCommands: limits.pendingWorkerCommands,
+    });
+}
+function hostPorts(authority, worker) {
+    return {
+        state: authority.state,
+        submit: worker.submit,
+        input: async (runId) => {
+            const digest = (await authority.state()).details[runId]?.input;
+            return typeof digest === "string"
+                ? await authority.queries.document(digest)
+                : undefined;
+        },
+        document: authority.queries.document,
+        requestEffect: worker.requestEffect,
+        reportEffect: worker.reportEffect,
+        openGate: worker.openGate,
+        registerWait: worker.registerWait,
+        operation: authority.effects.operation,
+        workflowId: async (runId) => (await authority.queries.workflowIds())[runId],
+    };
+}
+function message(error) {
+    return String(Reflect.get(Object(error), "message"));
+}
+async function hosted(options, ports) {
+    try {
+        return { kind: "started", host: await options.host?.(ports) };
+    }
+    catch (error) {
+        return refused("host-unavailable", message(error));
+    }
+}

package/dist/src/service/submission-handler.d.ts

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