@gajae-code/coding-agent 0.14.2 → 0.15.0

package/src/coordinator-mcp/durability.ts

@@ -0,0 +1,200 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+
+export interface CoordinatorDirectoryBarrierOptions {
+	platform?: NodeJS.Platform;
+	openDirectory?: (directory: string) => Promise<fs.FileHandle>;
+}
+
+export interface CoordinatorFileDurabilityOptions {
+	syncFile?: (handle: fs.FileHandle) => Promise<void>;
+}
+
+export interface CoordinatorAtomicWriteOptions
+	extends CoordinatorDirectoryBarrierOptions,
+		CoordinatorFileDurabilityOptions {
+	rename?: (source: string, destination: string) => Promise<void>;
+}
+
+/** The file was published, but its final directory barrier did not complete. */
+export class CoordinatorPublicationUncertainError extends Error {
+	constructor(cause: unknown) {
+		super("coordinator publication outcome is uncertain", { cause });
+	}
+}
+
+export async function ensureCoordinatorDirectory(
+	directory: string,
+	options: CoordinatorDirectoryBarrierOptions = {},
+): Promise<void> {
+	const missing: string[] = [];
+	for (let current = directory; ; current = path.dirname(current)) {
+		try {
+			const stat = await fs.stat(current);
+			if (!stat.isDirectory()) throw new Error(`coordinator directory is not a directory: ${current}`);
+			break;
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+			missing.push(current);
+			if (current === path.dirname(current)) throw error;
+		}
+	}
+	for (const created of missing.reverse()) {
+		try {
+			await fs.mkdir(created, { mode: 0o700 });
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+			const stat = await fs.stat(created);
+			if (!stat.isDirectory()) throw error;
+		}
+		await syncCoordinatorDirectory(path.dirname(created), options);
+	}
+}
+
+/**
+ * Windows does not support fsync on directory handles. File contents must be
+ * synced before publication; this barrier only makes the renamed directory
+ * entry durable where the platform supports that operation.
+ */
+export function isUnsupportedWindowsDirectorySyncError(
+	error: unknown,
+	platform: NodeJS.Platform = process.platform,
+): boolean {
+	if (platform !== "win32") return false;
+	const code = (error as NodeJS.ErrnoException | undefined)?.code;
+	// Windows directory-handle barriers use the established broker precedent:
+	// EPERM/EACCES are tolerated only for the directory open/sync operation.
+	return code === "EPERM" || code === "EACCES";
+}
+
+export async function syncCoordinatorDirectory(
+	directory: string,
+	options: CoordinatorDirectoryBarrierOptions = {},
+): Promise<void> {
+	let handle: fs.FileHandle;
+	try {
+		handle = await (options.openDirectory ?? (path => fs.open(path, "r")))(directory);
+	} catch (error) {
+		if (!isUnsupportedWindowsDirectorySyncError(error, options.platform)) throw error;
+		return;
+	}
+	let syncError: unknown;
+	try {
+		await handle.sync();
+	} catch (error) {
+		if (!isUnsupportedWindowsDirectorySyncError(error, options.platform)) syncError = error;
+	}
+	try {
+		await handle.close();
+	} catch (closeError) {
+		if (syncError) throw new AggregateError([syncError, closeError], "coordinator directory sync and close failed");
+		throw closeError;
+	}
+	if (syncError) throw syncError;
+}
+
+/** File durability is never best-effort: callers must abort on every failure. */
+export async function syncCoordinatorFile(
+	handle: fs.FileHandle,
+	options: CoordinatorFileDurabilityOptions = {},
+): Promise<void> {
+	await (options.syncFile ?? (file => file.sync()))(handle);
+}
+
+/** Append a durable coordinator journal or diagnostic record, then barrier its parent. */
+export async function appendCoordinatorFile(
+	file: string,
+	contents: string,
+	options: CoordinatorDirectoryBarrierOptions & CoordinatorFileDurabilityOptions = {},
+): Promise<void> {
+	await ensureCoordinatorDirectory(path.dirname(file), options);
+	let originalSize = 0;
+	try {
+		originalSize = (await fs.stat(file)).size;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+	}
+	const handle = await fs.open(file, "a", 0o600);
+	let writeError: unknown;
+	try {
+		await handle.writeFile(contents);
+		await syncCoordinatorFile(handle, options);
+	} catch (error) {
+		writeError = error;
+	}
+	if (writeError) {
+		try {
+			await handle.truncate(originalSize);
+			await syncCoordinatorFile(handle, options);
+		} catch (rollbackError) {
+			writeError = new AggregateError([writeError, rollbackError], "coordinator append rollback failed");
+		}
+	}
+	try {
+		await handle.close();
+	} catch (closeError) {
+		if (writeError) {
+			const writeErrors = writeError instanceof AggregateError ? writeError.errors : [writeError];
+			throw new AggregateError([...writeErrors, closeError], "coordinator append and close failed");
+		}
+		throw closeError;
+	}
+	if (writeError) throw writeError;
+	try {
+		await syncCoordinatorDirectory(path.dirname(file), options);
+	} catch (error) {
+		throw new CoordinatorPublicationUncertainError(error);
+	}
+}
+
+/** Atomically publish a synced coordinator state file, then barrier its parent. */
+export async function writeCoordinatorAtomic(
+	file: string,
+	contents: string,
+	options: CoordinatorAtomicWriteOptions = {},
+): Promise<void> {
+	await ensureCoordinatorDirectory(path.dirname(file), options);
+	const temporary = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`;
+	let published = false;
+	try {
+		const handle = await fs.open(temporary, "wx", 0o600);
+		let writeError: unknown;
+		try {
+			await handle.writeFile(contents);
+			await syncCoordinatorFile(handle, options);
+		} catch (error) {
+			writeError = error;
+		}
+		try {
+			await handle.close();
+		} catch (closeError) {
+			if (writeError) throw new AggregateError([writeError, closeError], "coordinator write and close failed");
+			throw closeError;
+		}
+		if (writeError) throw writeError;
+		await (options.rename ?? fs.rename)(temporary, file);
+		published = true;
+		await syncCoordinatorDirectory(path.dirname(file), options);
+	} catch (error) {
+		let cleanupError: unknown;
+		try {
+			await fs.rm(temporary, { force: true });
+		} catch (cleanupFailure) {
+			cleanupError = cleanupFailure;
+		}
+		let cleanupBarrierError: unknown;
+		if (!cleanupError && !published) {
+			try {
+				await syncCoordinatorDirectory(path.dirname(file), options);
+			} catch (barrierError) {
+				cleanupBarrierError = barrierError;
+			}
+		}
+		const failures = [error, cleanupError, cleanupBarrierError].filter(
+			(value): value is unknown => value !== undefined,
+		);
+		if (published) throw new CoordinatorPublicationUncertainError(new AggregateError(failures));
+		if (failures.length === 1) throw failures[0];
+		throw new AggregateError(failures, "coordinator atomic write and cleanup failed");
+	}
+}

package/src/coordinator-mcp/event-webhook.ts

@@ -0,0 +1,278 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { $credentialEnv } from "@gajae-code/utils/env";
+import { withFileLock } from "../config/file-lock";
+import { writeCoordinatorAtomic } from "./durability";
+
+/**
+ * Opt-in webhook delivery of existing coordinator `watch_events` journal rows
+ * (issue #4706). Delivery is a durable outbox keyed by the journal row's stable
+ * `id`: each delivered row is recorded once, retried with bounded exponential
+ * backoff, and never blocks or rewrites the journal append path.
+ */
+
+export interface EventWebhookConfig {
+	url: string;
+	tokenFile: string | null;
+	sessionIds: Set<string> | null;
+	timeoutMs: number;
+	maxAttempts: number;
+}
+
+interface WebhookDeliveryRecord {
+	schema_version: 1;
+	event_id: string;
+	status: "pending" | "delivered" | "failed";
+	attempts: number;
+	created_at: string;
+	updated_at: string;
+	last_error: string | null;
+}
+
+function isWebhookDeliveryRecord(value: unknown, eventId: string): value is WebhookDeliveryRecord {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const record = value as Record<string, unknown>;
+	return (
+		record.schema_version === 1 &&
+		record.event_id === eventId &&
+		(record.status === "pending" || record.status === "delivered" || record.status === "failed") &&
+		typeof record.attempts === "number" &&
+		Number.isSafeInteger(record.attempts) &&
+		record.attempts >= 0 &&
+		typeof record.created_at === "string" &&
+		typeof record.updated_at === "string" &&
+		(record.last_error === null || typeof record.last_error === "string")
+	);
+}
+
+/** Result of one webhook POST attempt; 2xx is ok, anything else carries the reason. */
+interface WebhookPostOutcome {
+	ok: boolean;
+	status: number | null;
+	error: string | null;
+}
+
+export interface WebhookDelivery {
+	/** Called with the exact JSON body to POST and per-attempt request options. */
+	post(
+		body: string,
+		options: { url: string; token: string | null; timeoutMs: number; signal: AbortSignal },
+	): Promise<WebhookPostOutcome>;
+	/** Test seam: delay between retries; default is `Bun.sleep`. */
+	sleep(ms: number): Promise<void>;
+	/** Monotonic-ish clock for deadline math; default is `Date.now`. */
+	now(): number;
+}
+
+/** Default `WebhookDelivery` over `fetch`: POST, 2xx = ok, no redirects, abort on timeout. */
+export function createDefaultEventWebhookDelivery(): WebhookDelivery {
+	return {
+		async post(body, options) {
+			const response = await fetch(options.url, {
+				method: "POST",
+				redirect: "error",
+				signal: options.signal,
+				headers: {
+					"content-type": "application/json",
+					...(options.token ? { authorization: `Bearer ${options.token}` } : {}),
+				},
+				body,
+			});
+			// Drain the body so the socket is reusable, then treat non-2xx as failure.
+			await response.text().catch(() => "");
+			if (!response.ok) return { ok: false, status: response.status, error: `http_${response.status}` };
+			return { ok: true, status: response.status, error: null };
+		},
+		sleep: async ms => {
+			await Bun.sleep(ms);
+		},
+		now: () => Date.now(),
+	};
+}
+
+export const DEFAULT_EVENT_WEBHOOK_TIMEOUT_MS = 5_000;
+export const MAX_EVENT_WEBHOOK_TIMEOUT_MS = 30_000;
+export const DEFAULT_EVENT_WEBHOOK_MAX_ATTEMPTS = 5;
+export const MAX_EVENT_WEBHOOK_MAX_ATTEMPTS = 10;
+const WEBHOOK_BACKOFF_BASE_MS = 500;
+const WEBHOOK_BACKOFF_CAP_MS = 15_000;
+const WEBHOOK_ERROR_CAP = 240;
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "::1", "localhost"]);
+
+/**
+ * Trusted-source resolution for the five webhook variables. Egress destination
+ * and the token-file path must never come from the caller's cwd `.env` overlay:
+ * Bun loads that overlay into `process.env`, so a raw `process.env` read would
+ * let any repository select where coordinator journal rows are POSTed.
+ * `$credentialEnv` consults only the inherited environment and GJC/user-owned
+ * env files, exactly like the crash relay's DSN. Callers that own a fully
+ * controlled environment (tests, rendered hermes blocks) pass `explicitEnv`;
+ * production entry points must omit it and resolve through the trusted source.
+ */
+function webhookEnvValue(explicitEnv: NodeJS.ProcessEnv | undefined, name: string): string | undefined {
+	const explicit = explicitEnv?.[name]?.trim();
+	if (explicit) return explicit;
+	return $credentialEnv(name)?.trim() || undefined;
+}
+
+export function parseEventWebhookConfig(explicitEnv?: NodeJS.ProcessEnv): EventWebhookConfig | null {
+	const rawUrl = webhookEnvValue(explicitEnv, "GJC_COORDINATOR_MCP_EVENT_WEBHOOK_URL");
+	if (!rawUrl) return null;
+	let parsed: URL;
+	try {
+		parsed = new URL(rawUrl);
+	} catch {
+		throw new Error("coordinator_event_webhook_url_invalid");
+	}
+	const hostname = parsed.hostname.replace(/^\[|\]$/g, "").toLowerCase();
+	if (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && LOOPBACK_HOSTS.has(hostname)))
+		throw new Error("coordinator_event_webhook_url_not_allowed");
+	const rawSessions = webhookEnvValue(explicitEnv, "GJC_COORDINATOR_MCP_EVENT_WEBHOOK_SESSION_IDS");
+	const sessionIds = rawSessions
+		? new Set(
+				rawSessions
+					.split(",")
+					.map(value => value.trim())
+					.filter(value => /^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$/.test(value)),
+			)
+		: null;
+	const tokenFile = webhookEnvValue(explicitEnv, "GJC_COORDINATOR_MCP_EVENT_WEBHOOK_TOKEN_FILE") ?? "";
+	if (tokenFile !== "" && !path.isAbsolute(tokenFile)) throw new Error("coordinator_event_webhook_token_file_invalid");
+	const timeoutRaw = Number.parseInt(
+		webhookEnvValue(explicitEnv, "GJC_COORDINATOR_MCP_EVENT_WEBHOOK_TIMEOUT_MS") ?? "",
+		10,
+	);
+	const timeoutMs =
+		Number.isFinite(timeoutRaw) && timeoutRaw > 0
+			? Math.min(timeoutRaw, MAX_EVENT_WEBHOOK_TIMEOUT_MS)
+			: DEFAULT_EVENT_WEBHOOK_TIMEOUT_MS;
+	const attemptsRaw = Number.parseInt(
+		webhookEnvValue(explicitEnv, "GJC_COORDINATOR_MCP_EVENT_WEBHOOK_MAX_ATTEMPTS") ?? "",
+		10,
+	);
+	const maxAttempts =
+		Number.isFinite(attemptsRaw) && attemptsRaw > 0
+			? Math.min(attemptsRaw, MAX_EVENT_WEBHOOK_MAX_ATTEMPTS)
+			: DEFAULT_EVENT_WEBHOOK_MAX_ATTEMPTS;
+	return { url: rawUrl, tokenFile: tokenFile || null, sessionIds, timeoutMs, maxAttempts };
+}
+
+function eventWebhookScopeApplies(config: EventWebhookConfig, event: { session_id?: string }): boolean {
+	return config.sessionIds === null || (event.session_id !== undefined && config.sessionIds.has(event.session_id));
+}
+
+function recordPath(namespaceDir: string, eventId: string): string {
+	if (!/^event-\d{12,}$/.test(eventId)) throw new Error("coordinator_event_webhook_event_id_invalid");
+	return path.join(namespaceDir, "webhook-outbox", `${eventId}.json`);
+}
+
+async function readRecord(file: string, eventId: string): Promise<WebhookDeliveryRecord | null> {
+	let source: string;
+	try {
+		source = await fs.readFile(file, "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+		throw error;
+	}
+	try {
+		const parsed: unknown = JSON.parse(source);
+		return isWebhookDeliveryRecord(parsed, eventId) ? parsed : null;
+	} catch (error) {
+		if (error instanceof SyntaxError) return null;
+		throw error;
+	}
+}
+
+async function writeRecord(file: string, record: WebhookDeliveryRecord): Promise<void> {
+	await writeCoordinatorAtomic(file, JSON.stringify(record));
+}
+
+function webhookErrorSummary(error: string | null): string | null {
+	if (error === null) return null;
+	const normalized = error.replace(/[\r\n]+/g, " ").trim();
+	return normalized.length > WEBHOOK_ERROR_CAP ? `${normalized.slice(0, WEBHOOK_ERROR_CAP - 3)}...` : normalized;
+}
+
+function backoffDelayMs(attempt: number): number {
+	return Math.min(WEBHOOK_BACKOFF_BASE_MS * 2 ** (attempt - 1), WEBHOOK_BACKOFF_CAP_MS);
+}
+
+async function readWebhookToken(tokenFile: string | null): Promise<string | null> {
+	if (tokenFile === null) return null;
+	try {
+		return (await fs.readFile(tokenFile, "utf8")).trim();
+	} catch {
+		throw new Error("coordinator_event_webhook_token_file_unreadable");
+	}
+}
+
+/**
+ * Records the row in the durable outbox and, unless the row is already
+ * delivered or exhausted, performs one bounded delivery attempt series. The
+ * returned promise settles only after bounded attempts/backoff, so a dead sink
+ * can never wedge the caller's persistence; callers run it off the append path.
+ */
+export async function deliverEventWebhook(
+	namespaceDir: string,
+	config: EventWebhookConfig,
+	event: { id: string; session_id?: string },
+	renderBody: () => string,
+	delivery: WebhookDelivery,
+): Promise<void> {
+	if (!eventWebhookScopeApplies(config, event)) return;
+	const file = recordPath(namespaceDir, event.id);
+	return await withFileLock(file, async () => {
+		const now0 = delivery.now();
+		let record = await readRecord(file, event.id);
+		if (record === null) {
+			record = {
+				schema_version: 1,
+				event_id: event.id,
+				status: "pending",
+				attempts: 0,
+				created_at: new Date(now0).toISOString(),
+				updated_at: new Date(now0).toISOString(),
+				last_error: null,
+			};
+			await writeRecord(file, record);
+		} else if (record.status !== "pending") {
+			return;
+		}
+		const token = await readWebhookToken(config.tokenFile);
+		const body = renderBody();
+		while (record.attempts < config.maxAttempts) {
+			record.attempts += 1;
+			const controller = new AbortController();
+			const timer = setTimeout(() => controller.abort(), config.timeoutMs);
+			timer.unref?.();
+			let outcome: WebhookPostOutcome;
+			try {
+				outcome = await delivery.post(body, {
+					url: config.url,
+					token,
+					timeoutMs: config.timeoutMs,
+					signal: controller.signal,
+				});
+			} catch (error) {
+				outcome = { ok: false, status: null, error: error instanceof Error ? error.message : String(error) };
+			} finally {
+				clearTimeout(timer);
+			}
+			const ts = new Date(delivery.now()).toISOString();
+			record.updated_at = ts;
+			record.last_error = outcome.ok ? null : webhookErrorSummary(outcome.error);
+			if (outcome.ok) {
+				record.status = "delivered";
+				await writeRecord(file, record);
+				return;
+			}
+			if (record.attempts >= config.maxAttempts) {
+				record.status = "failed";
+				await writeRecord(file, record);
+				return;
+			}
+			await writeRecord(file, record);
+			await delivery.sleep(backoffDelayMs(record.attempts));
+		}
+	});
+}