@bastani/atomic 0.9.13 → 0.9.14-alpha.1

package/dist/builtin/workflows/src/extension/workflow-heartbeat-delivery.ts

@@ -0,0 +1,197 @@
+import type { WorkflowHeartbeatEventDetails } from "../shared/workflow-heartbeat-contract.js";
+
+/** Timer seam so the scheduler and its retries are testable without real waiting. */
+export interface WorkflowHeartbeatTimerHandle {
+	unref?: () => void;
+}
+
+export interface WorkflowHeartbeatTimerApi {
+	setTimeout(handler: () => void, delayMs: number): WorkflowHeartbeatTimerHandle;
+	clearTimeout(handle: WorkflowHeartbeatTimerHandle): void;
+}
+
+export const defaultWorkflowHeartbeatTimerApi: WorkflowHeartbeatTimerApi = {
+	setTimeout: (handler, delayMs) => setTimeout(handler, delayMs) as WorkflowHeartbeatTimerHandle,
+	clearTimeout: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+};
+
+/**
+ * Attempts a single heartbeat identity is given before its pending slot is
+ * released. A heartbeat is a periodic nudge, not an exactly-once terminal
+ * notice: retrying forever would hold the run's one pending slot and silence
+ * every later boundary on the cadence. Releasing the slot lets the next future
+ * boundary arm normally.
+ */
+export const WORKFLOW_HEARTBEAT_MAX_DELIVERY_ATTEMPTS = 5;
+
+interface WorkflowHeartbeatDeliveryOptions {
+	readonly emit: (details: WorkflowHeartbeatEventDetails) => boolean | Promise<boolean>;
+	/**
+	 * Live re-check taken immediately before every attempt, the retries included.
+	 * A run that reached a terminal state between attempt 1 and attempt 5 must not
+	 * be sent, so the guard belongs on the attempt rather than on the enqueue.
+	 */
+	readonly canDeliver?: (details: WorkflowHeartbeatEventDetails) => boolean;
+	/** Called exactly once per identity, after success or after attempts are exhausted. */
+	readonly onSettled: (details: WorkflowHeartbeatEventDetails, delivered: boolean) => void;
+	readonly timers: WorkflowHeartbeatTimerApi;
+}
+
+export interface WorkflowHeartbeatDelivery {
+	deliver(details: WorkflowHeartbeatEventDetails): void;
+	/**
+	 * Drop every not-yet-attempted identity belonging to one run, and cancel the
+	 * backoff timer of a head that belongs to it, then start the next identity.
+	 *
+	 * Terminal cleanup's queue half (issue #1975). A send already handed to the
+	 * host cannot be recalled, so an in-flight head stays where it is — but it is
+	 * marked, so whatever the host answers settles straight through instead of
+	 * arming a retry for a run that is already finished. Its `onSettled` is inert
+	 * at the scheduler too, because the pending slot is gone by then. Returns
+	 * whether anything was dropped, so a spared in-flight head alone reports
+	 * `false`.
+	 */
+	discard(runId: string): boolean;
+	dispose(): void;
+}
+
+/** Stable delivery key for one boundary: the slice-1 `runId + scheduledAt` identity. */
+export function workflowHeartbeatIdentityKey(identity: { runId: string; scheduledAt: number }): string {
+	return `${identity.runId}:${identity.scheduledAt}`;
+}
+
+/**
+ * Owns heartbeat admission: one identity at a time, in the order handed over,
+ * with capped-backoff retry.
+ *
+ * **Why the queue exists.** The scheduler sorts a due batch by `scheduledAt`
+ * then `runId` and hands identities over in that order, but sorting only
+ * controls the order attempts *start*. If the first identity's send is rejected
+ * it enters backoff, and a later identity admitted in the meantime reaches the
+ * parent first — the observed order becomes B, A. Admission order is what the
+ * ordering rule is about, so the queue holds later identities until the head
+ * reaches a terminal result: admitted, suppressed by its guard, or out of
+ * attempts.
+ *
+ * Every retry re-sends the identical `WorkflowHeartbeatEventDetails`, so the
+ * `runId + scheduledAt` identity is reused rather than re-derived from the
+ * retry's own clock. Deliberately separate from `createLifecycleNoticeDelivery`:
+ * that helper is hard-typed to lifecycle notices and its exact retry/handover
+ * semantics are pinned by existing tests.
+ */
+export function createWorkflowHeartbeatDelivery(options: WorkflowHeartbeatDeliveryOptions): WorkflowHeartbeatDelivery {
+	const retryTimers = new Set<WorkflowHeartbeatTimerHandle>();
+	const queue: WorkflowHeartbeatEventDetails[] = [];
+	let attempt = 0;
+	let running = false;
+	let active = true;
+	/**
+	 * Whether the in-flight head was discarded while its send was outstanding.
+	 *
+	 * The send itself cannot be recalled, but its *result* must not start a
+	 * retry: a rejection arriving after cleanup would otherwise arm a backoff
+	 * timer, and re-attempt the old identity, for a run whose cleanup already
+	 * finished. One boolean suffices because only one head is ever in flight,
+	 * and `settleHead` — the only path that shifts the queue — clears it, so it
+	 * can never carry over to the next identity or to another run.
+	 */
+	let headDiscarded = false;
+
+	/** Finish the head identity and start the next one, in handover order. */
+	const settleHead = (details: WorkflowHeartbeatEventDetails, delivered: boolean): void => {
+		queue.shift();
+		attempt = 0;
+		running = false;
+		headDiscarded = false;
+		options.onSettled(details, delivered);
+		runHead();
+	};
+
+	const runHead = (): void => {
+		if (!active || running || retryTimers.size > 0) return;
+		const details = queue[0];
+		if (details === undefined) return;
+		// The live guard runs immediately before every attempt, including the
+		// first attempt of an identity that waited behind another one — the run
+		// may have finished or paused while it queued.
+		if (options.canDeliver !== undefined && !options.canDeliver(details)) {
+			// Suppressed rather than sent, and never retried: the run's state is the
+			// reason, and no amount of backoff changes it. Later identities proceed.
+			settleHead(details, false);
+			return;
+		}
+		running = true;
+		attempt += 1;
+		const thisAttempt = attempt;
+		const settle = (delivered: boolean): void => {
+			// A discarded head settles straight through, whatever the host answered:
+			// no retry, and the real result is still reported once.
+			if (delivered || headDiscarded || thisAttempt >= WORKFLOW_HEARTBEAT_MAX_DELIVERY_ATTEMPTS || !active) {
+				settleHead(details, delivered);
+				return;
+			}
+			running = false;
+			const handle = options.timers.setTimeout(
+				() => {
+					retryTimers.delete(handle);
+					runHead();
+				},
+				Math.min(20 * 2 ** (thisAttempt - 1), 1_000),
+			);
+			handle.unref?.();
+			retryTimers.add(handle);
+		};
+		const result = options.emit(details);
+		if (typeof result === "boolean") settle(result);
+		else void result.then(settle);
+	};
+
+	const deliver = (details: WorkflowHeartbeatEventDetails): void => {
+		if (!active) return;
+		queue.push(details);
+		runHead();
+	};
+
+	const discard = (runId: string): boolean => {
+		// An attempt is already with the host and cannot be recalled, so the head
+		// is spared only while its send is genuinely in flight. A head sitting in
+		// backoff has nothing outstanding and is dropped with its timer.
+		const head = queue[0];
+		const headInFlight = running && head !== undefined && head.runId === runId;
+		let discarded = false;
+		// Back to front, so index 0 is decided last and the indices ahead of it
+		// stay valid while they are spliced out.
+		for (let index = queue.length - 1; index >= 0; index -= 1) {
+			if (queue[index]?.runId !== runId) continue;
+			if (index === 0 && headInFlight) {
+				// Spared, but invalidated: its settlement must not schedule a retry.
+				headDiscarded = true;
+				continue;
+			}
+			queue.splice(index, 1);
+			discarded = true;
+			if (index > 0) continue;
+			// The dropped head owned the attempt counter and, if it was waiting to
+			// retry, the only live backoff timer.
+			attempt = 0;
+			running = false;
+			for (const handle of retryTimers) options.timers.clearTimeout(handle);
+			retryTimers.clear();
+		}
+		if (discarded) runHead();
+		return discarded;
+	};
+
+	return {
+		deliver,
+		discard,
+		dispose() {
+			active = false;
+			for (const handle of retryTimers) options.timers.clearTimeout(handle);
+			retryTimers.clear();
+			queue.length = 0;
+			// An in-flight send is left to settle on its own; `active` keeps it from
+			// starting a further retry.
+		},
+	};
+}

package/dist/builtin/workflows/src/extension/workflow-heartbeat-notice.ts

@@ -0,0 +1,115 @@
+import {
+	WORKFLOW_HEARTBEAT_CUSTOM_TYPE,
+	type WorkflowHeartbeatEventDetails,
+} from "../shared/workflow-heartbeat-contract.js";
+import { deriveGraphThemeFromPiTheme, type GraphTheme } from "../tui/graph-theme.js";
+import { renderWorkflowNoticeCard } from "../tui/workflow-notice-card.js";
+import type { ExtensionAPI, PiMessageRenderComponent, PiMessageRenderer } from "./index.js";
+
+/** Card title and glyph, both distinct from every lifecycle notice kind. */
+const WORKFLOW_HEARTBEAT_TITLE = "WORKFLOW HEARTBEAT";
+const WORKFLOW_HEARTBEAT_GLYPH = "♥";
+
+const rendererRegisteredHosts = new WeakSet<object>();
+
+/**
+ * Model-facing heartbeat text. Derived only from the five slice-1 payload
+ * fields: it names the workflow and run so the parent can identify the work,
+ * states the cadence and elapsed time so it can judge drift, and points at the
+ * existing status surface so it can inspect rather than guess.
+ */
+export function formatWorkflowHeartbeatNoticeText(details: WorkflowHeartbeatEventDetails): string {
+	const workflowName = escapeQuotedText(details.workflowName);
+	const elapsed = formatWorkflowHeartbeatElapsed(details);
+	const cadence = formatWorkflowHeartbeatCadence(details.intervalMinutes);
+	return (
+		`${WORKFLOW_HEARTBEAT_GLYPH} Workflow "${workflowName}" heartbeat (run ${details.runId}) — still running` +
+		`${elapsed === undefined ? "" : ` after ${elapsed}`}, on a ${cadence} cadence. ` +
+		"This is a periodic alignment check, not a failure. Review whether the run is still on goal, then " +
+		"continue, steer it, stop and replace it, or ask the user. " +
+		`Inspect: /workflow status ${details.runId}`
+	);
+}
+
+export interface WorkflowHeartbeatRendererOptions {
+	readonly registerMessageRenderer?: ExtensionAPI["registerMessageRenderer"];
+	readonly rendererHost?: object;
+}
+
+export function registerWorkflowHeartbeatRenderer(options: WorkflowHeartbeatRendererOptions): void {
+	const register = options.registerMessageRenderer;
+	if (typeof register !== "function") return;
+
+	const host = options.rendererHost ?? register;
+	if (rendererRegisteredHosts.has(host)) return;
+
+	const renderer: PiMessageRenderer = (raw, _options, piTheme) => {
+		const message = raw as { details?: WorkflowHeartbeatEventDetails };
+		if (!message.details) return undefined;
+		return makeWorkflowHeartbeatComponent(message.details, themeFromRenderer(piTheme));
+	};
+
+	register(WORKFLOW_HEARTBEAT_CUSTOM_TYPE, renderer);
+	rendererRegisteredHosts.add(host);
+}
+
+function makeWorkflowHeartbeatComponent(
+	details: WorkflowHeartbeatEventDetails,
+	theme: GraphTheme | undefined,
+): PiMessageRenderComponent {
+	const text = formatWorkflowHeartbeatNoticeText(details);
+	return {
+		render(width: number): string[] {
+			return renderWorkflowHeartbeatCard(details, { width, theme, fallbackText: text });
+		},
+		invalidate() {
+			/* delivered heartbeats are immutable */
+		},
+	};
+}
+
+function renderWorkflowHeartbeatCard(
+	details: WorkflowHeartbeatEventDetails,
+	opts: { width: number; theme?: GraphTheme; fallbackText: string },
+): string[] {
+	return renderWorkflowNoticeCard({
+		title: WORKFLOW_HEARTBEAT_TITLE,
+		glyph: WORKFLOW_HEARTBEAT_GLYPH,
+		headline: `Workflow "${details.workflowName}" is still running`,
+		tone: "mauve",
+		fields: [
+			{ label: "workflow", value: details.workflowName },
+			{ label: "run", value: details.runId },
+			{ label: "cadence", value: formatWorkflowHeartbeatCadence(details.intervalMinutes), tone: "muted" },
+			{ label: "elapsed", value: formatWorkflowHeartbeatElapsed(details), tone: "muted" },
+		],
+		hints: [`/workflow status ${details.runId}`],
+		fallbackText: opts.fallbackText,
+		width: opts.width,
+		...(opts.theme ? { theme: opts.theme } : {}),
+	});
+}
+
+function formatWorkflowHeartbeatCadence(intervalMinutes: number): string {
+	return `${intervalMinutes}-minute`;
+}
+
+/** Elapsed run time at the boundary, derived from the payload's own timestamps. */
+function formatWorkflowHeartbeatElapsed(details: WorkflowHeartbeatEventDetails): string | undefined {
+	const elapsedMs = details.scheduledAt - details.startedAt;
+	if (!Number.isFinite(elapsedMs) || elapsedMs < 0) return undefined;
+	const totalMinutes = Math.floor(elapsedMs / 60_000);
+	if (totalMinutes < 1) return `${Math.max(0, Math.floor(elapsedMs / 1000))}s`;
+	if (totalMinutes < 60) return `${totalMinutes}m`;
+	const hours = Math.floor(totalMinutes / 60);
+	const minutes = totalMinutes % 60;
+	return minutes === 0 ? `${hours}h` : `${hours}h ${minutes}m`;
+}
+
+function escapeQuotedText(value: string): string {
+	return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+function themeFromRenderer(piTheme: unknown): GraphTheme | undefined {
+	return piTheme === undefined ? undefined : deriveGraphThemeFromPiTheme(piTheme);
+}