@shivaedev/work-fleet 0.0.0 → 0.1.1

package/src/host/config.ts

@@ -0,0 +1,111 @@
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+import { CONFIG_FILE, DEFAULT_NAMESPACE, NAMESPACE, SHARED_LOCAL_POSTGRES } from "#host/defaults.ts";
+import { DEFAULT_AREA_MERGE_WAIT_MS } from "#scheduling/areas.ts";
+import { LaunchSettings } from "#session/schema.ts";
+
+const Positive = Schema.Int.check(Schema.isGreaterThan(0));
+const Text = Schema.String.check(Schema.isMinLength(1));
+const Guidance = Schema.Union([Text, Schema.Struct({ file: Text })]);
+
+export const HostConfig = Schema.Struct({
+	areaMergeWaitMs: Schema.optional(Positive),
+	backlog: Schema.optional(Positive),
+	cloud: Schema.optional(
+		Schema.Struct({
+			archiveThreads: Schema.optional(Schema.Boolean),
+			authFile: Schema.optional(Text),
+			cwd: Text,
+			endpoint: Schema.optional(Text),
+			environmentId: Text,
+			projectId: Schema.optional(Text),
+			refreshCommand: Schema.optional(Schema.Struct({ args: Schema.Array(Schema.String), command: Text })),
+			requestTimeoutMs: Schema.optional(Positive),
+			threadNamePrefix: Schema.optional(Text),
+			writableRoots: Schema.optional(Schema.Array(Text)),
+		}),
+	),
+	concurrency: Schema.optional(Positive),
+	database: Schema.optional(Schema.Struct({ maxConnections: Schema.optional(Positive), url: Schema.optional(Text) })),
+	intervalSeconds: Schema.optional(Positive),
+	launch: Schema.optional(LaunchSettings),
+	local: Schema.optional(Schema.Struct({ endpoint: Text, requestTimeoutMs: Schema.optional(Positive) })),
+	namespace: Schema.optional(Schema.String.check(Schema.isPattern(NAMESPACE))),
+	provider: Schema.Literals(["local", "cloud"]),
+	quota: Schema.optional(Schema.Literals(["codex", "unlimited"])),
+	repository: Schema.optional(Schema.Struct({ branch: Text, remote: Text })),
+	result: Schema.optional(Schema.Literal("github")),
+	stallMinutes: Schema.optional(Positive),
+	worker: Schema.optional(
+		Schema.Struct({
+			branchPrefix: Text,
+			reviewerGuidance: Schema.optional(Guidance),
+			sharedEnvironment: Text,
+			workerGuidance: Schema.optional(Guidance),
+		}),
+	),
+});
+export type HostConfig = typeof HostConfig.Type;
+
+export class HostFailure extends Schema.TaggedError<HostFailure>()("HostFailure", { message: Schema.String }) {}
+
+export interface FleetHost {
+	readonly areaMergeWaitMs: number;
+	readonly backlog: number;
+	readonly boardDir: string;
+	readonly cloud: HostConfig["cloud"];
+	readonly concurrency: number;
+	readonly databaseUrl: string;
+	readonly interval: number;
+	readonly launch: NonNullable<HostConfig["launch"]>;
+	readonly local: HostConfig["local"];
+	readonly maxConnections: number;
+	readonly namespace: string;
+	readonly provider: HostConfig["provider"];
+	readonly quota: NonNullable<HostConfig["quota"]>;
+	readonly repository: NonNullable<HostConfig["repository"]>;
+	readonly result?: HostConfig["result"];
+	readonly stallMinutes: number;
+	readonly worker: HostConfig["worker"];
+}
+
+export function resolveHost(boardDir: string, config: HostConfig): FleetHost {
+	return {
+		areaMergeWaitMs: config.areaMergeWaitMs ?? DEFAULT_AREA_MERGE_WAIT_MS,
+		backlog: config.backlog ?? 100,
+		boardDir,
+		cloud: config.cloud,
+		concurrency: config.concurrency ?? 100,
+		databaseUrl: config.database?.url ?? SHARED_LOCAL_POSTGRES,
+		interval: config.intervalSeconds ?? 15,
+		launch: config.launch ?? {},
+		local: config.local,
+		maxConnections: config.database?.maxConnections ?? 20,
+		namespace: config.namespace ?? DEFAULT_NAMESPACE,
+		provider: config.provider,
+		quota: config.quota ?? "codex",
+		repository: config.repository ?? { branch: "main", remote: "origin" },
+		result: config.result,
+		stallMinutes: config.stallMinutes ?? 30,
+		worker: config.worker,
+	};
+}
+
+export const loadHost = Effect.fn("FleetHost.loadHost")(function* (board: string, configPath?: string) {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const boardDir = path.resolve(board);
+	const file = configPath === undefined ? path.join(boardDir, CONFIG_FILE) : path.resolve(configPath);
+	const text = yield* fs
+		.readFileString(file)
+		.pipe(Effect.mapError(() => new HostFailure({ message: `Fleet host configuration is missing or unreadable: ${file}` })));
+	const config = yield* Schema.decodeUnknownEffect(Schema.fromJsonString(HostConfig))(text).pipe(
+		Effect.mapError((error) => new HostFailure({ message: `Fleet host configuration ${file} is invalid: ${error.message}` })),
+	);
+	if (config.provider === "cloud" && (config.cloud === undefined || config.worker === undefined)) {
+		return yield* new HostFailure({ message: `Fleet host configuration ${file} selects provider "cloud" without cloud and worker settings` });
+	}
+	return resolveHost(boardDir, config);
+});

package/src/host/continuationMessage.ts

@@ -0,0 +1,19 @@
+import process from "node:process";
+import type { Readable } from "node:stream";
+import { text } from "node:stream/consumers";
+import { Effect } from "effect";
+import { BadRequest } from "@shivaedev/platform/errors/taxonomy.ts";
+
+export function continuationMessage(message: string | undefined, input: Readable = process.stdin) {
+	const failure = new BadRequest({ message: "Supply a continuation message as an argument or on stdin" });
+	if (message === undefined && input === process.stdin && process.stdin.isTTY) {
+		return Effect.fail(failure);
+	}
+	const read = message === undefined ? Effect.tryPromise({ catch: () => failure, try: () => text(input) }) : Effect.succeed(message);
+	return read.pipe(
+		Effect.filterOrFail(
+			(value) => value.trim().length > 0,
+			() => failure,
+		),
+	);
+}

package/src/host/daemon.ts

@@ -0,0 +1,45 @@
+import { Context, Effect, Fiber, Layer } from "effect";
+import { appHost } from "@shivaedev/platform/appHost.ts";
+import { diagnostics as diagnosticsApi } from "@shivaedev/work-board/integration/diagnostics.ts";
+import { type HostParts, hostLayer, hostScheduler, productionParts } from "#host/commands.ts";
+import type { FleetHost } from "#host/config.ts";
+import { DaemonContract, RPC_PATH } from "#host/daemonContract.ts";
+import { daemonHandlers } from "#host/daemonHandlers.ts";
+import { fleetHandlers } from "#operations.ts";
+
+const { DAEMON_PORT: DEFAULT_DAEMON_PORT } = diagnosticsApi;
+
+export const DAEMON_HOST = "127.0.0.1";
+export const DAEMON_PORT = DEFAULT_DAEMON_PORT;
+
+class Scheduler extends Context.Service<Scheduler, Fiber.Fiber<void, unknown>>()("@shivaedev/work-fleet/DaemonScheduler") {}
+
+export function daemonHostOptions(host: FleetHost, parts: HostParts = productionParts(host), port: number = DAEMON_PORT) {
+	return {
+		config: { disablePreemptiveShutdown: true, host: DAEMON_HOST, port },
+		group: DaemonContract,
+		handlers: Layer.merge(fleetHandlers, Layer.unwrap(daemonHandlers(host))),
+		policy: "loopback" as const,
+		rpcPath: RPC_PATH,
+		services: hostLayer(host, parts),
+	};
+}
+
+export function daemonLayer(host: FleetHost, parts: HostParts = productionParts(host), port: number = DAEMON_PORT) {
+	const http = daemonHttpLayer(daemonHostOptions(host, parts, port));
+	const scheduler = Layer.effect(Scheduler)(hostScheduler(host).pipe(Effect.forkScoped));
+	return scheduler.pipe(Layer.provideMerge(http));
+}
+
+export function daemonHttpLayer(options: ReturnType<typeof daemonHostOptions>) {
+	return appHost({ ...options, services: Layer.empty }).pipe(Layer.provideMerge(options.services));
+}
+
+export function serveFleet(host: FleetHost, parts: HostParts = productionParts(host), port: number = DAEMON_PORT) {
+	return Effect.scoped(
+		Effect.gen(function* () {
+			const context = yield* Layer.build(daemonLayer(host, parts, port));
+			return yield* Fiber.join(Context.get(context, Scheduler));
+		}),
+	);
+}

package/src/host/daemonClient.ts

@@ -0,0 +1,36 @@
+import { Effect, Layer } from "effect";
+import { FetchHttpClient } from "effect/http";
+import { RpcClient, RpcSerialization } from "effect/rpc";
+import { RpcClientError } from "effect/rpc/RpcClientError";
+import { ServiceUnavailable } from "@shivaedev/platform/errors/taxonomy.ts";
+import { diagnostics as diagnosticsApi } from "@shivaedev/work-board/integration/diagnostics.ts";
+import { isFleetError } from "#errors.ts";
+import { DaemonContract, RPC_PATH } from "#host/daemonContract.ts";
+
+const { DAEMON_PORT } = diagnosticsApi;
+
+export function daemonClient(port: number = DAEMON_PORT) {
+	return RpcClient.make(DaemonContract, { flatten: true }).pipe(
+		Effect.provide(
+			RpcClient.layerProtocolHttp({ url: `http://127.0.0.1:${port}${RPC_PATH}` }).pipe(
+				Layer.provide([FetchHttpClient.layer, RpcSerialization.layerNdjson]),
+			),
+		),
+	);
+}
+
+export function daemonRequest<A, E, R>(port: number, use: (client: Effect.Success<ReturnType<typeof daemonClient>>) => Effect.Effect<A, E, R>) {
+	return Effect.scoped(daemonClient(port).pipe(Effect.flatMap(use))).pipe(Effect.mapError((error) => daemonError(error, port)));
+}
+
+export function daemonError(error: unknown, port: number) {
+	if (isFleetError(error)) {
+		return error;
+	}
+	const transport = error instanceof RpcClientError && error.reason._tag === "HttpError" && error.reason.kind === "TransportError";
+	return new ServiceUnavailable({
+		message: transport
+			? `No Fleet daemon is running at 127.0.0.1:${port}; start work-fleet serve <board-dir> --port ${port}`
+			: `Fleet daemon communication failed at 127.0.0.1:${port}: ${error instanceof Error ? error.message : String(error)}`,
+	});
+}

package/src/host/daemonContract.ts

@@ -0,0 +1,64 @@
+import { Schema } from "effect";
+import { contract } from "@shivaedev/effect-contract/contract.ts";
+import { command, query, stream } from "@shivaedev/effect-contract/operation.ts";
+import { RequestTracing } from "@shivaedev/platform/rpc/middleware.ts";
+import { diagnostics as diagnosticsApi } from "@shivaedev/work-board/integration/diagnostics.ts";
+import { fleetRejections } from "#errors.ts";
+import { FleetRecord, FleetViews } from "#model.ts";
+import { FleetContract, fleetRecords } from "#operations.ts";
+
+const { DAEMON_RPC_PATH, DiagnosticsContract } = diagnosticsApi;
+
+export const ClientContract = contract("daemon", {
+	commands: [
+		command("release", {
+			invalidates: ({ workIds }) => [fleetRecords.list, ...workIds.map(fleetRecords.item)],
+			payload: { workIds: Schema.Array(Schema.String) },
+			rejections: fleetRejections,
+			success: Schema.Array(FleetRecord),
+		}),
+		command("answer", {
+			invalidates: ({ workId }) => [fleetRecords.list, fleetRecords.item(workId)],
+			payload: { release: Schema.optional(Schema.Boolean), text: Schema.optional(Schema.String), workId: Schema.String },
+			rejections: fleetRejections,
+			success: FleetRecord,
+		}),
+		command("name-threads", {
+			invalidates: () => [],
+			payload: {},
+			rejections: fleetRejections,
+			success: Schema.Array(Schema.Struct({ error: Schema.Boolean, message: Schema.String })),
+		}),
+		command("dispatch", {
+			invalidates: ({ workId }) => [fleetRecords.list, fleetRecords.item(workId)],
+			payload: { workId: Schema.String },
+			rejections: fleetRejections,
+			success: FleetRecord,
+		}),
+	],
+	queries: [
+		query("status", {
+			payload: { workId: Schema.optional(Schema.String) },
+			reads: ({ workId }) => [workId === undefined ? fleetRecords.list : fleetRecords.item(workId)],
+			rejections: fleetRejections,
+			success: FleetViews,
+		}),
+	],
+	streams: [
+		stream("follow", {
+			payload: { follow: Schema.optional(Schema.Boolean), workIds: Schema.Array(Schema.String) },
+			reads: ({ workIds }) => [fleetRecords.list, ...workIds.map(fleetRecords.item)],
+			rejections: fleetRejections,
+			success: Schema.Array(Schema.Unknown),
+		}),
+	],
+});
+export const Follow = (() => {
+	const rpc = [...ClientContract.requests.values()].find((request) => request._tag === "daemon.follow");
+	if (rpc === undefined) {
+		throw new Error("Daemon contract must declare its follow stream");
+	}
+	return rpc;
+})();
+export const DaemonContract = FleetContract.merge(ClientContract, DiagnosticsContract).middleware(RequestTracing);
+export const RPC_PATH = DAEMON_RPC_PATH;

package/src/host/daemonDiagnostics.ts

@@ -0,0 +1,20 @@
+import { Effect } from "effect";
+import { diagnostics as diagnosticsApi } from "@shivaedev/work-board/integration/diagnostics.ts";
+import { HealthSnapshot } from "#engine/health.ts";
+import { fleetItems } from "#host/fleetItems.ts";
+
+const { codexLimits, DiagnosticsContract, DiagnosticsSources, diagnostics, githubLimits } = diagnosticsApi;
+
+export const daemonDiagnostics = Effect.gen(function* () {
+	const provided = yield* Effect.serviceOption(DiagnosticsSources);
+	const sources = {
+		codex: provided._tag === "Some" ? provided.value.codex : codexLimits(),
+		fleet: yield* HealthSnapshot,
+		github: provided._tag === "Some" ? provided.value.github : githubLimits(),
+	};
+	const read = yield* diagnostics(sources);
+	const items = yield* fleetItems;
+	return DiagnosticsContract.toLayer(
+		Effect.succeed(DiagnosticsContract.of({ "daemon.diagnostics": () => read, "daemon.fleetItems": () => items.pipe(Effect.orDie) })),
+	);
+});

package/src/host/daemonHandlers.ts

@@ -0,0 +1,33 @@
+import { Effect, Layer } from "effect";
+import { exposeFailure } from "#exposeFailure.ts";
+import { dispatchApproved } from "#host/admission.ts";
+import { answerWork } from "#host/answerWork.ts";
+import type { FleetHost } from "#host/config.ts";
+import { ClientContract } from "#host/daemonContract.ts";
+import { daemonDiagnostics } from "#host/daemonDiagnostics.ts";
+import { daemonSnapshots } from "#host/daemonSnapshots.ts";
+import { nameStoredThreads } from "#host/nameThreads.ts";
+import { releaseItems } from "#host/releaseWork.ts";
+import { fleetStatus } from "#host/status.ts";
+
+export const daemonHandlers = Effect.fn("FleetDaemon.daemonHandlers")(function* (host: FleetHost) {
+	const follow = yield* daemonSnapshots(host);
+	const diagnostics = yield* daemonDiagnostics;
+	return Layer.merge(
+		diagnostics,
+		ClientContract.toLayer(
+			Effect.succeed(
+				ClientContract.of({
+					"daemon.answer": ({ workId, text, release }) =>
+						exposeFailure(answerWork(host, workId, text, release).pipe(Effect.map(({ value }) => value))),
+					"daemon.dispatch": ({ workId }) => exposeFailure(dispatchApproved(host, workId).pipe(Effect.map(({ value }) => value))),
+					"daemon.follow": ({ workIds, follow: continuous }) => follow(workIds, continuous),
+					"daemon.name-threads": () => exposeFailure(nameStoredThreads(host)),
+					"daemon.release": ({ workIds }) =>
+						exposeFailure(releaseItems(host, workIds).pipe(Effect.map((records) => records.map(({ value }) => value)))),
+					"daemon.status": ({ workId }) => exposeFailure(fleetStatus(host, workId)),
+				}),
+			),
+		),
+	);
+});

package/src/host/daemonSnapshots.ts

@@ -0,0 +1,24 @@
+import { Effect, Schedule, Stream } from "effect";
+import { SqlClient } from "effect/sql";
+import { AppChanges } from "@shivaedev/platform/appHost.ts";
+import { ServiceUnavailable } from "@shivaedev/platform/errors/taxonomy.ts";
+import { fleetRecords } from "#fleetRecords.ts";
+import type { FleetHost } from "#host/config.ts";
+import { readWaitStates } from "#host/readWaitStates.ts";
+import { snapshotStream } from "#host/snapshotStream.ts";
+
+export const daemonSnapshots = Effect.fn("FleetDaemon.daemonSnapshots")(function* (host: FleetHost) {
+	const sql = yield* SqlClient.SqlClient;
+	const changes = yield* AppChanges;
+	const read = readWaitStates(host).pipe(
+		Effect.provideService(SqlClient.SqlClient, sql),
+		Effect.retry({ schedule: Schedule.spaced("500 millis"), times: 19 }),
+		Effect.mapError(() => new ServiceUnavailable({ message: "Fleet daemon could not read work states after 20 consecutive attempts" })),
+	);
+	const snapshots = yield* changes.stream([fleetRecords.list, { _tag: "List", collection: `${host.namespace}_records` }]).pipe(
+		Stream.mapEffect(() => read),
+		Stream.changesWith((left, right) => JSON.stringify(left) === JSON.stringify(right)),
+		Stream.share({ capacity: 1, replay: 1, strategy: "sliding" }),
+	);
+	return (ids: readonly string[], continuous = false) => snapshotStream(snapshots, ids, continuous);
+});

package/src/host/defaults.ts

@@ -0,0 +1,4 @@
+export const CONFIG_FILE = "fleet.config.json";
+export const SHARED_LOCAL_POSTGRES = "postgresql://postgres:postgres@127.0.0.1:55432/platform_dev";
+export const DEFAULT_NAMESPACE = "work_fleet";
+export const NAMESPACE = /^[a-z_][a-z\d_]{0,40}$/u;

package/src/host/fleetItems.ts

@@ -0,0 +1,33 @@
+import { Clock, Effect } from "effect";
+import { waitingOwner } from "#attention.ts";
+import { FleetRepository } from "#engine/repository.ts";
+import type { FleetRecord } from "#model.ts";
+
+function item(record: FleetRecord) {
+	return {
+		attentionOwner: waitingOwner(record),
+		prUrl: record.result?.kind === "change" ? record.result.pr : undefined,
+		stage: record.stage,
+		stageEnteredAt: record.stageEnteredAt ?? null,
+		updatedAt: record.updatedAt ?? null,
+		workId: record.workId,
+	};
+}
+export const fleetItems = Effect.gen(function* () {
+	const store = yield* FleetRepository;
+	return Effect.gen(function* () {
+		const now = yield* Clock.currentTimeMillis;
+		const records = (yield* store.list()).map(({ value }) => value);
+		return {
+			completed: records.flatMap((record) =>
+				record.stage === "completed"
+				&& record.completedAt !== undefined
+				&& record.completedAt >= now - 7 * 24 * 60 * 60 * 1000
+				&& record.completedAt <= now
+					? [{ ...item(record), completedAt: record.completedAt, stage: "completed" as const }]
+					: [],
+			),
+			items: records.filter((record) => record.stage !== "completed" && record.stage !== "released").map(item),
+		};
+	});
+});

package/src/host/follow.ts

@@ -0,0 +1,44 @@
+import { Effect, Stream } from "effect";
+import { diagnostics as diagnosticsApi } from "@shivaedev/work-board/integration/diagnostics.ts";
+import { type FleetError, isFleetError } from "#errors.ts";
+import { daemonClient, daemonError } from "#host/daemonClient.ts";
+import { decodeFollowState, type FollowState } from "#host/followState.ts";
+
+const { DAEMON_PORT } = diagnosticsApi;
+
+export interface FollowOptions {
+	readonly follow?: boolean;
+	readonly intervalMs: number;
+	readonly port?: number;
+	readonly timeoutMs?: number;
+}
+
+export function follow(options: FollowOptions, workIds: readonly string[]) {
+	const port = options.port ?? DAEMON_PORT;
+	let ids = workIds;
+	let connected = false;
+	let failures = 0;
+	function connect(): Stream.Stream<readonly FollowState[], FleetError> {
+		return Stream.unwrap(daemonClient(port).pipe(Effect.map((client) => client("daemon.follow", { follow: options.follow, workIds: ids })))).pipe(
+			Stream.scoped,
+			Stream.map((states) => states.map(decodeFollowState)),
+			Stream.map((states) => {
+				if (!(options.follow || connected) && ids.length === 0) {
+					ids = states.map((state) => state.workId);
+				}
+				connected = true;
+				failures = 0;
+				return states;
+			}),
+			Stream.concat(Stream.fail(new Error("Fleet daemon subscription closed"))),
+			Stream.catch((error) => {
+				failures += 1;
+				if (!connected || isFleetError(error) || failures >= 20) {
+					return Stream.fail(daemonError(error, port));
+				}
+				return Stream.unwrap(Effect.sleep(options.intervalMs).pipe(Effect.as(connect())));
+			}),
+		);
+	}
+	return connect();
+}

package/src/host/followCommands.ts

@@ -0,0 +1,54 @@
+import process from "node:process";
+import * as Console from "effect/Console";
+import * as Argument from "effect/cli/Argument";
+import * as Command from "effect/cli/Command";
+import * as Flag from "effect/cli/Flag";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { board, config, port } from "#host/cliOptions.ts";
+
+export const waitCommand = Command.make(
+	"wait",
+	{
+		board,
+		config,
+		interval: Flag.Finite("interval").pipe(Flag.withDefault(15), Flag.withDescription("Seconds between daemon reconnect attempts")),
+		port,
+		timeout: Flag.Finite("timeout").pipe(Flag.optional, Flag.withDescription("Give up after this many seconds (exit 4)")),
+		workId: Argument.String("id"),
+	},
+	Effect.fn("WorkFleetCli.wait")(function* (input) {
+		const { waitFor } = yield* Effect.promise(() => import("#host/wait.ts"));
+		const outcome = yield* waitFor({
+			intervalMs: input.interval * 1000,
+			port: input.port,
+			workId: input.workId,
+			...Option.match(input.timeout, { onNone: () => ({}), onSome: (seconds) => ({ timeoutMs: seconds * 1000 }) }),
+		});
+		yield* Console.log(outcome.summary);
+		process.exitCode = outcome.code;
+	}),
+).pipe(Command.withDescription("Block until the work completes (exit 0), needs a human (2) or is released (3); 4 on --timeout, 1 on errors"));
+
+export const watchCommand = Command.make(
+	"watch",
+	{
+		board,
+		config,
+		follow: Flag.Boolean("follow").pipe(Flag.withDefault(false), Flag.withDescription("Keep watching transitions, including newly launched work")),
+		interval: Flag.Finite("interval").pipe(Flag.withDefault(15), Flag.withDescription("Seconds between daemon reconnect attempts")),
+		port,
+		timeout: Flag.Finite("timeout").pipe(Flag.optional, Flag.withDescription("Give up after this many seconds (exit 4)")),
+		workIds: Argument.String("id").pipe(Argument.variadic()),
+	},
+	Effect.fn("WorkFleetCli.watch")(function* (input) {
+		const { watchFor } = yield* Effect.promise(() => import("#host/watch.ts"));
+		process.exitCode = yield* watchFor({
+			follow: input.follow,
+			intervalMs: input.interval * 1000,
+			port: input.port,
+			workIds: input.workIds,
+			...Option.match(input.timeout, { onNone: () => ({}), onSome: (seconds) => ({ timeoutMs: seconds * 1000 }) }),
+		});
+	}),
+).pipe(Command.withDescription("Print item outcomes; --follow keeps watching transitions and new work until interrupted"));

package/src/host/followState.ts

@@ -0,0 +1,41 @@
+import { Option, Schema } from "effect";
+import { DecisionCode } from "#DecisionCode.ts";
+import { State, settled, WAIT_EXIT, type WaitOutcome } from "#host/waitOutcome.ts";
+import { FleetRecord } from "#model.ts";
+
+export interface FollowState extends Schema.Schema.Type<typeof State> {
+	readonly undecoded?: string;
+}
+
+const Identity = Schema.Struct({ stage: Schema.optional(Schema.String), workId: Schema.optional(Schema.String) });
+
+export function decodeFollowState(value: unknown): FollowState {
+	const decoded = Schema.decodeUnknownOption(State)(value);
+	if (Option.isSome(decoded)) {
+		return decoded.value;
+	}
+	const fields = Option.getOrElse(Schema.decodeUnknownOption(Identity)(value), () => ({ stage: undefined, workId: undefined }));
+	return { stage: fields.stage ?? "unknown", undecoded: JSON.stringify(value), workId: fields.workId ?? "unknown" };
+}
+
+export function unrecognizedState(state: FollowState): boolean {
+	return (
+		state.undecoded !== undefined
+		|| !Schema.is(FleetRecord.fields.stage)(state.stage)
+		|| (state.decision?.code !== undefined && !Schema.is(DecisionCode)(state.decision.code))
+	);
+}
+
+export function followOutcome(state: FollowState): WaitOutcome | undefined {
+	if (state.undecoded !== undefined) {
+		return { code: WAIT_EXIT.error, summary: `${state.workId} ${state.stage}: ${state.undecoded}` };
+	}
+	const outcome = settled(state.workId, state);
+	const code = state.decision?.code;
+	if (code !== undefined && !Schema.is(DecisionCode)(code)) {
+		return { code: outcome?.code ?? WAIT_EXIT.error, summary: `${outcome?.summary ?? `${state.workId} ${state.stage}`}: ${code}` };
+	}
+	return (
+		outcome ?? (Schema.is(FleetRecord.fields.stage)(state.stage) ? undefined : { code: WAIT_EXIT.error, summary: `${state.workId} ${state.stage}` })
+	);
+}

package/src/host/github.ts

@@ -0,0 +1,32 @@
+import { Effect, Schema } from "effect";
+import { ServiceUnavailable } from "@shivaedev/platform/errors/taxonomy.ts";
+import type { FleetError } from "#errors.ts";
+
+const Sha = Schema.String.check(Schema.isPattern(/^[a-f\d]{40}$/u));
+const Positive = Schema.Int.check(Schema.isGreaterThan(0));
+export const PullRequest = Schema.Struct({
+	base: Schema.Struct({ ref: Schema.String, sha: Sha }),
+	changedFiles: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+	head: Schema.Struct({ sha: Sha }),
+	htmlUrl: Schema.String,
+	merged: Schema.Boolean,
+	number: Positive,
+	state: Schema.Literals(["open", "closed"]),
+}).pipe(Schema.encodeKeys({ changedFiles: "changed_files", htmlUrl: "html_url" }));
+export const FilePages = Schema.Array(
+	Schema.Array(
+		Schema.Struct({ filename: Schema.String, previousFilename: Schema.optional(Schema.String) }).pipe(
+			Schema.encodeKeys({ previousFilename: "previous_filename" }),
+		),
+	),
+);
+export const Repository = Schema.Struct({ nameWithOwner: Schema.String });
+
+export type GithubRead = (args: readonly string[]) => Effect.Effect<string, FleetError>;
+
+export function githubJson<TSchema extends Schema.Top>(schema: TSchema, read: GithubRead, args: readonly string[]) {
+	return read(args).pipe(
+		Effect.flatMap(Schema.decodeUnknownEffect(Schema.fromJsonString(schema))),
+		Effect.mapError(() => new ServiceUnavailable({ message: "GitHub observation failed or returned invalid data" })),
+	);
+}

package/src/host/githubCheckState.ts

@@ -0,0 +1,95 @@
+import { Schema } from "effect";
+import type { Checks } from "#policy.ts";
+
+const CheckRun = Schema.Struct({
+	completedAt: Schema.optional(Schema.NullOr(Schema.String)),
+	conclusion: Schema.NullOr(Schema.String),
+	detailsUrl: Schema.NullOr(Schema.String),
+	headSha: Schema.String,
+	htmlUrl: Schema.String,
+	name: Schema.String,
+	startedAt: Schema.optional(Schema.NullOr(Schema.String)),
+	status: Schema.String,
+}).pipe(
+	Schema.encodeKeys({ completedAt: "completed_at", detailsUrl: "details_url", headSha: "head_sha", htmlUrl: "html_url", startedAt: "started_at" }),
+);
+export const CheckPages = Schema.Array(Schema.Struct({ checkRuns: Schema.Array(CheckRun) }).pipe(Schema.encodeKeys({ checkRuns: "check_runs" })));
+const Status = Schema.Struct({ context: Schema.String, state: Schema.String, targetUrl: Schema.NullOr(Schema.String) }).pipe(
+	Schema.encodeKeys({ targetUrl: "target_url" }),
+);
+export const StatusPages = Schema.Array(Schema.Struct({ sha: Schema.String, statuses: Schema.Array(Status) }));
+
+interface Observation {
+	readonly name: string;
+	readonly state: "pass" | "fail" | "pending";
+	readonly url: string;
+}
+function checkState(check: typeof CheckRun.Type): Observation["state"] {
+	if (check.status !== "completed" || check.conclusion === null) {
+		return "pending";
+	}
+	if (["success", "neutral", "skipped"].includes(check.conclusion)) {
+		return "pass";
+	}
+	return ["failure", "cancelled", "timed_out", "action_required", "stale", "startup_failure"].includes(check.conclusion) ? "fail" : "pending";
+}
+function statusState(state: string): Observation["state"] {
+	if (state === "success") {
+		return "pass";
+	}
+	return ["error", "failure"].includes(state) ? "fail" : "pending";
+}
+function newestChecks(pages: typeof CheckPages.Type) {
+	const newest = new Map<string, typeof CheckRun.Type>();
+	function time(check: typeof CheckRun.Type) {
+		return Date.parse(check.completedAt ?? check.startedAt ?? "") || 0;
+	}
+	for (const check of pages.flatMap((page) => page.checkRuns)) {
+		const previous = newest.get(check.name);
+		if (previous === undefined || time(check) > time(previous)) {
+			newest.set(check.name, check);
+		}
+	}
+	return [...newest.values()];
+}
+export function githubCheckState(
+	head: string,
+	pr: string,
+	checks: typeof CheckPages.Type,
+	statuses: typeof StatusPages.Type,
+	required: readonly string[],
+): Checks {
+	const observations: Observation[] = [
+		...newestChecks(checks).map((check) => ({ name: check.name, state: checkState(check), url: check.detailsUrl ?? check.htmlUrl })),
+		...statuses.flatMap((page) =>
+			page.statuses.map(
+				(status): Observation => ({
+					name: status.context,
+					state: statusState(status.state),
+					url: status.targetUrl ?? `${pr.split("/pull/")[0]}/commit/${head}/checks`,
+				}),
+			),
+		),
+	];
+	function isRequired(name: string) {
+		return required.length === 0 || required.includes(name);
+	}
+	const evidence = observations.map((check) => `${check.name}${isRequired(check.name) ? "" : " (non-required)"}: ${check.state} ${check.url}`);
+	const gates = observations.filter((check) => isRequired(check.name));
+	const missing = required.filter((name) => !gates.some((check) => check.name === name));
+	evidence.push(...missing.map((name) => `${name}: pending (required check has not reported)`));
+	const failures = gates.filter((check) => check.state === "fail");
+	const pending = failures.length === 0 && (gates.length === 0 || missing.length > 0 || gates.some((check) => check.state === "pending"));
+	return {
+		evidence,
+		failedChecks: [...new Set(failures.map((check) => check.name))].sort(),
+		head,
+		passed: failures.length === 0 && !pending,
+		pending,
+		...(failures.length === 0
+			? {}
+			: {
+					repairPrompt: `Fix the failing GitHub checks for ${pr} at ${head}:\n${failures.map((check) => `${check.name}: ${check.url}`).join("\n")}`,
+				}),
+	};
+}