pi-harness-runtime 1.1.394 → 1.1.396

package/packages/logging/src/singleton.ts

@@ -0,0 +1,142 @@
+/**
+ * The process-wide logging singleton.
+ *
+ * The singleton lives in the package (not in the harness) so that every
+ * producer - the root extension and the harness modules - shares exactly one
+ * shipper, one buffer and one spool.
+ *
+ * Nothing here throws: a logging failure must never break the caller.
+ */
+
+import { resolveLogSinkConfig, type LogSinkConfig } from "./config.js";
+import { LogShipper } from "./shipper.js";
+import { LogSpool } from "./spool.js";
+import type { LogLevel } from "./types.js";
+
+export interface InitCentralLoggingOptions {
+	/** Environment used for the configuration. Defaults to `process.env`. */
+	env?: Record<string, string | undefined>;
+	/** Directory holding the credential key files. */
+	keysDir?: string;
+}
+
+let shipper: LogShipper | null = null;
+let config: LogSinkConfig | null = null;
+
+/**
+ * Initialize the centralized logging pipeline.
+ *
+ * Calling it twice is safe: the second call returns the existing
+ * configuration without creating a second shipper.
+ */
+export function initCentralLogging(
+	options: InitCentralLoggingOptions = {},
+): LogSinkConfig | null {
+	if (config) return config;
+
+	try {
+		const resolved = resolveLogSinkConfig({
+			env: options.env ?? process.env,
+			keysDir: options.keysDir,
+		});
+		config = resolved;
+
+		if (!resolved.enabled) return resolved;
+
+		const spool = resolved.spoolDir ? new LogSpool({ dir: resolved.spoolDir }) : undefined;
+		shipper = new LogShipper({
+			app: resolved.app,
+			transports: resolved.transports,
+			spool,
+			buffer: resolved.buffer,
+			sampling: resolved.sampling,
+			flushIntervalMs: resolved.flushIntervalMs,
+		});
+		shipper.start();
+
+		// The exit handler is synchronous on purpose: an async flush cannot
+		// run during `exit`, so the remaining records go to the local spool.
+		process.once("exit", () => {
+			shipper?.flushSync();
+		});
+
+		return resolved;
+	} catch {
+		return null;
+	}
+}
+
+/** The active shipper, or null when logging is not initialized. */
+export function getCentralShipper(): LogShipper | null {
+	return shipper;
+}
+
+/** The resolved configuration, or null when logging was never initialized. */
+export function getCentralLogConfig(): LogSinkConfig | null {
+	return config;
+}
+
+/** Emit one record. No-op when the pipeline is not initialized. */
+export function centralLog(
+	level: LogLevel,
+	source: string,
+	event: string,
+	message?: string,
+	fields?: Record<string, unknown>,
+	error?: unknown,
+): void {
+	try {
+		shipper?.log({ level, source, event, message, fields, error });
+	} catch {
+		// Never let logging break the caller.
+	}
+}
+
+export function centralDebug(
+	source: string,
+	event: string,
+	message?: string,
+	fields?: Record<string, unknown>,
+): void {
+	centralLog("debug", source, event, message, fields);
+}
+
+export function centralInfo(
+	source: string,
+	event: string,
+	message?: string,
+	fields?: Record<string, unknown>,
+): void {
+	centralLog("info", source, event, message, fields);
+}
+
+export function centralWarn(
+	source: string,
+	event: string,
+	message?: string,
+	fields?: Record<string, unknown>,
+): void {
+	centralLog("warn", source, event, message, fields);
+}
+
+export function centralError(
+	source: string,
+	event: string,
+	message?: string,
+	fields?: Record<string, unknown>,
+	error?: unknown,
+): void {
+	centralLog("error", source, event, message, fields, error);
+}
+
+/** Flush and stop the pipeline. Safe to call when it was never started. */
+export async function shutdownCentralLogging(): Promise<void> {
+	if (!shipper) return;
+	const current = shipper;
+	shipper = null;
+	try {
+		await current.stop();
+	} catch {
+		// Nothing to do at shutdown time.
+	}
+}

package/packages/logging/src/spool.ts

@@ -0,0 +1,139 @@
+/**
+ * Local NDJSON spool - the last-resort destination for log batches.
+ *
+ * When every transport fails (no network, R2 down, webhook server down) the
+ * batch is written to disk instead of being lost. The spool is drained on
+ * the next successful flush, so a temporary outage does not cost data.
+ *
+ * Files are plain NDJSON, one record per line, so an operator can inspect
+ * them with `tail`, `jq` or `less` without any tooling.
+ */
+
+import {
+	appendFileSync,
+	existsSync,
+	mkdirSync,
+	readdirSync,
+	readFileSync,
+	renameSync,
+	rmSync,
+	statSync,
+} from "node:fs";
+import { join } from "node:path";
+import type { LogBatch, LogRecord } from "./types.js";
+
+export interface LogSpoolOptions {
+	/** Directory that holds the spool files. */
+	dir: string;
+	/** Rotate a file when it would exceed this size. Default 5 MB. */
+	maxFileBytes?: number;
+	/** Maximum number of spool files kept. Default 20. */
+	maxFiles?: number;
+}
+
+const FILE_PREFIX = "logs-spool-";
+const FILE_SUFFIX = ".ndjson";
+
+export class LogSpool {
+	private readonly dir: string;
+	private readonly maxFileBytes: number;
+	private readonly maxFiles: number;
+
+	constructor(options: LogSpoolOptions) {
+		this.dir = options.dir;
+		this.maxFileBytes = Math.max(1024, options.maxFileBytes ?? 5 * 1024 * 1024);
+		this.maxFiles = Math.max(1, options.maxFiles ?? 20);
+	}
+
+	/** Append a batch to the spool. Returns the file that was written. */
+	append(batch: LogBatch, now: Date = new Date()): string {
+		this.ensureDir();
+		const file = this.currentFile(now);
+		const payload = batch.records.map((record) => JSON.stringify(record)).join("\n") + "\n";
+
+		if (this.shouldRotate(file, payload.length)) {
+			this.rotate(file);
+		}
+
+		appendFileSync(file, payload, "utf8");
+		this.enforceRetention();
+		return file;
+	}
+
+	/** Spool files, oldest first. */
+	list(): string[] {
+		if (!existsSync(this.dir)) return [];
+		return readdirSync(this.dir)
+			.filter(
+				(name) =>
+					name.startsWith(FILE_PREFIX) &&
+					(name.endsWith(FILE_SUFFIX) || new RegExp(`\\${FILE_SUFFIX}\\.\\d+$`).test(name)),
+			)
+			.map((name) => join(this.dir, name))
+			.sort();
+	}
+
+	/** Read the records of a spool file. */
+	read(file: string): LogRecord[] {
+		if (!existsSync(file)) return [];
+		const content = readFileSync(file, "utf8");
+		const records: LogRecord[] = [];
+		for (const line of content.split("\n")) {
+			const trimmed = line.trim();
+			if (!trimmed) continue;
+			try {
+				records.push(JSON.parse(trimmed) as LogRecord);
+			} catch {
+				// A truncated last line is expected after a crash; skip it.
+			}
+		}
+		return records;
+	}
+
+	/** Delete a spool file after it was shipped. */
+	remove(file: string): void {
+		try {
+			rmSync(file, { force: true });
+		} catch {
+			// Nothing to do - the file stays and is retried later.
+		}
+	}
+
+	private ensureDir(): void {
+		if (!existsSync(this.dir)) {
+			mkdirSync(this.dir, { recursive: true });
+		}
+	}
+
+	private currentFile(now: Date): string {
+		const day = now.toISOString().slice(0, 10);
+		return join(this.dir, `${FILE_PREFIX}${day}${FILE_SUFFIX}`);
+	}
+
+	private shouldRotate(file: string, incomingBytes: number): boolean {
+		if (!existsSync(file)) return false;
+		try {
+			return statSync(file).size + incomingBytes > this.maxFileBytes;
+		} catch {
+			return false;
+		}
+	}
+
+	private rotate(file: string): void {
+		for (let index = 1; index <= this.maxFiles; index++) {
+			const candidate = `${file}.${index}`;
+			if (!existsSync(candidate)) {
+				renameSync(file, candidate);
+				return;
+			}
+		}
+	}
+
+	private enforceRetention(): void {
+		const files = this.list();
+		const extra = files.length - this.maxFiles;
+		for (let i = 0; i < extra; i++) {
+			this.remove(files[i]);
+		}
+	}
+}

package/packages/logging/src/transports/r2.ts

@@ -0,0 +1,86 @@
+/**
+ * Cloudflare R2 transport.
+ *
+ * Batches are uploaded as NDJSON objects under a date-partitioned prefix so
+ * a bucket can be queried by day without listing every object:
+ *
+ *   logs/harness/2026/10/24/09/20261024T091500-abc123.ndjson.gz
+ *
+ * The AWS SDK is imported lazily so the package stays usable (and testable)
+ * without the SDK installed, and so a missing dependency surfaces as a
+ * transport error instead of a crash at startup.
+ */
+
+import { gzipSync } from "node:zlib";
+import type { LogBatch, LogTransport } from "../types.js";
+
+export interface R2TransportOptions {
+	/** R2 bucket name. */
+	bucket: string;
+	/** R2 endpoint, e.g. https://<account>.r2.cloudflarestorage.com */
+	endpoint: string;
+	accessKeyId: string;
+	secretAccessKey: string;
+	/** Key prefix inside the bucket. Default "logs/harness". */
+	prefix?: string;
+	/** Region label; R2 uses "auto". Default "auto". */
+	region?: string;
+	/** gzip the payload. Default true. */
+	gzip?: boolean;
+}
+
+/** Build the date-partitioned object key for a batch. */
+export function r2ObjectKey(prefix: string, batch: LogBatch): string {
+	const sentAt = new Date(batch.sentAt);
+	const year = sentAt.getUTCFullYear();
+	const month = String(sentAt.getUTCMonth() + 1).padStart(2, "0");
+	const day = String(sentAt.getUTCDate()).padStart(2, "0");
+	const hour = String(sentAt.getUTCHours()).padStart(2, "0");
+	return `${prefix}/${year}/${month}/${day}/${hour}/${batch.batchId}.ndjson`;
+}
+
+export function createR2Transport(options: R2TransportOptions): LogTransport {
+	const prefix = options.prefix ?? "logs/harness";
+	const region = options.region ?? "auto";
+	const gzip = options.gzip ?? true;
+
+	return {
+		name: "r2",
+		async send(batch: LogBatch): Promise<void> {
+			if (batch.records.length === 0) return;
+
+			let s3: typeof import("@aws-sdk/client-s3");
+			try {
+				s3 = await import("@aws-sdk/client-s3");
+			} catch (error) {
+				throw new Error(
+					`R2 transport requires @aws-sdk/client-s3: ${error instanceof Error ? error.message : String(error)}`,
+				);
+			}
+
+			const client = new s3.S3Client({
+				region,
+				endpoint: options.endpoint,
+				credentials: {
+					accessKeyId: options.accessKeyId,
+					secretAccessKey: options.secretAccessKey,
+				},
+			});
+
+			const payload = batch.records.map((record) => JSON.stringify(record)).join("\n") + "\n";
+			const body = gzip ? gzipSync(payload) : payload;
+			const key = `${r2ObjectKey(prefix, batch)}${gzip ? ".gz" : ""}`;
+
+			await client.send(
+				new s3.PutObjectCommand({
+					Bucket: options.bucket,
+					Key: key,
+					Body: body,
+					ContentType: gzip ? "application/gzip" : "application/x-ndjson",
+				}),
+			);
+
+			client.destroy();
+		},
+	};
+}

package/packages/logging/src/transports/webhook.ts

@@ -0,0 +1,54 @@
+/**
+ * Webhook transport.
+ *
+ * Delivers batches over HTTP to the existing unified webhook server
+ * (`POST /api/logs`). This is the low-latency path: the server can fan the
+ * batch out to alerting, while R2 keeps the durable archive.
+ */
+
+import type { LogBatch, LogTransport } from "../types.js";
+
+export interface WebhookTransportOptions {
+	/** Full URL of the ingest endpoint. */
+	url: string;
+	/** Optional bearer token. */
+	token?: string;
+	/** Extra headers. */
+	headers?: Record<string, string>;
+	/** Request timeout in milliseconds. Default 10000. */
+	timeoutMs?: number;
+	/** Custom fetch implementation (tests). */
+	fetchImpl?: typeof fetch;
+}
+
+export function createWebhookTransport(options: WebhookTransportOptions): LogTransport {
+	const timeoutMs = options.timeoutMs ?? 10_000;
+	const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+
+	return {
+		name: "webhook",
+		async send(batch: LogBatch): Promise<void> {
+			if (batch.records.length === 0) return;
+			if (typeof fetchImpl !== "function") {
+				throw new Error("Webhook transport requires a fetch implementation");
+			}
+
+			const headers: Record<string, string> = {
+				"Content-Type": "application/json",
+				...options.headers,
+			};
+			if (options.token) headers.Authorization = `Bearer ${options.token}`;
+
+			const response = await fetchImpl(options.url, {
+				method: "POST",
+				headers,
+				body: JSON.stringify(batch),
+				signal: AbortSignal.timeout(timeoutMs),
+			});
+
+			if (!response.ok) {
+				throw new Error(`Webhook transport failed with HTTP ${response.status}`);
+			}
+		},
+	};
+}

package/packages/logging/src/types.ts

@@ -0,0 +1,85 @@
+/**
+ * Log Sink - shared types for the centralized logging pipeline.
+ *
+ * The pipeline has three layers:
+ *   1. `LogRecord` - the structured, redacted unit that every producer emits.
+ *   2. `LogBatch`  - the transport unit (NDJSON over R2 or HTTP to the webhook).
+ *   3. `LogTransport` - the pluggable delivery mechanism.
+ *
+ * Producers never know which transport is configured; the shipper owns that
+ * decision, including the fallback order and the local spool.
+ */
+
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+/** Severity order used by the sampler and the buffer drop policy. */
+export const LOG_LEVEL_SEVERITY: Record<LogLevel, number> = {
+	debug: 10,
+	info: 20,
+	warn: 30,
+	error: 40,
+};
+
+export interface LogErrorInfo {
+	name: string;
+	message: string;
+	stack?: string;
+}
+
+/** A single structured log record. */
+export interface LogRecord {
+	/** ISO-8601 timestamp of the event. */
+	ts: string;
+	level: LogLevel;
+	/** Emitting component, e.g. "jev-judge" or "harness.service-diagnostics". */
+	source: string;
+	/** Dotted event name, e.g. "service.config_checked". */
+	event: string;
+	message?: string;
+	sessionId?: string;
+	durationMs?: number;
+	/** Structured, already redacted payload. */
+	fields?: Record<string, unknown>;
+	error?: LogErrorInfo;
+}
+
+/** What a producer hands to the shipper. */
+export interface LogInput {
+	level: LogLevel;
+	source: string;
+	event: string;
+	message?: string;
+	sessionId?: string;
+	durationMs?: number;
+	fields?: Record<string, unknown>;
+	/** Anything thrown - converted to a `LogErrorInfo` by the shipper. */
+	error?: unknown;
+}
+
+/** The transport unit: a batch of records shipped together. */
+export interface LogBatch {
+	batchId: string;
+	app: string;
+	host: string;
+	sentAt: string;
+	records: LogRecord[];
+}
+
+/** A delivery mechanism. Throwing means "delivery failed". */
+export interface LogTransport {
+	readonly name: string;
+	send(batch: LogBatch): Promise<void>;
+}
+
+export interface FlushStats {
+	/** Records handed to a transport successfully. */
+	shipped: number;
+	/** Records written to the local spool after every transport failed. */
+	spooled: number;
+	/** Records dropped by the buffer because it was full. */
+	dropped: number;
+	/** Records dropped by the sampler (level, sample rate, rate limit). */
+	sampled: number;
+	/** Transport errors, keyed by transport name. */
+	errors: Record<string, string>;
+}

package/packages/logging/test/buffer.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, test } from "bun:test";
+import { LogBuffer } from "../src/buffer.js";
+import type { LogRecord } from "../src/types.js";
+
+function record(level: LogRecord["level"], id: number): LogRecord {
+	return {
+		ts: "2026-10-24T00:00:00.000Z",
+		level,
+		source: "test",
+		event: `event-${id}`,
+	};
+}
+
+describe("LogBuffer", () => {
+	test("takes records in order and respects the batch size", () => {
+		const buffer = new LogBuffer({ maxSize: 10, maxBatchSize: 2 });
+		buffer.push(record("info", 1));
+		buffer.push(record("info", 2));
+		buffer.push(record("info", 3));
+
+		const batch = buffer.takeBatch();
+		expect(batch).toHaveLength(2);
+		expect(batch[0].event).toBe("event-1");
+		expect(buffer.size).toBe(1);
+	});
+
+	test("drops the least severe record when full", () => {
+		const buffer = new LogBuffer({ maxSize: 2, maxBatchSize: 10 });
+		buffer.push(record("error", 1));
+		buffer.push(record("info", 2));
+		buffer.push(record("debug", 3));
+
+		expect(buffer.dropped).toBe(1);
+		const batch = buffer.takeBatch();
+		expect(batch.map((item) => item.event)).toEqual(["event-1", "event-3"]);
+	});
+
+	test("peekAll does not consume the buffer", () => {
+		const buffer = new LogBuffer({ maxSize: 10, maxBatchSize: 10 });
+		buffer.push(record("info", 1));
+		expect(buffer.peekAll()).toHaveLength(1);
+		expect(buffer.size).toBe(1);
+	});
+});

package/packages/logging/test/config.test.ts

@@ -0,0 +1,97 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { resolveLogSinkConfig } from "../src/config.js";
+
+const created: string[] = [];
+
+function tempDir(): string {
+	const dir = mkdtempSync(join(tmpdir(), "log-config-"));
+	created.push(dir);
+	return dir;
+}
+
+afterEach(() => {
+	while (created.length > 0) {
+		rmSync(created.pop() as string, { recursive: true, force: true });
+	}
+});
+
+describe("resolveLogSinkConfig", () => {
+	test("PI_LOG_SINK=off disables logging completely", () => {
+		const config = resolveLogSinkConfig({ env: { PI_LOG_SINK: "off" }, keysDir: tempDir() });
+		expect(config.enabled).toBe(false);
+		expect(config.transports).toHaveLength(0);
+		expect(config.spoolDir).toBeUndefined();
+	});
+
+	test("auto mode stays local when nothing is configured", () => {
+		const config = resolveLogSinkConfig({ env: {}, keysDir: tempDir() });
+		expect(config.enabled).toBe(true);
+		expect(config.transports).toHaveLength(0);
+		expect(config.spoolDir).toBeTruthy();
+	});
+
+	test("auto mode picks up R2 credentials from the key files", () => {
+		const keysDir = tempDir();
+		writeFileSync(join(keysDir, "r2-bucket-name.txt"), "logs-bucket\n");
+		writeFileSync(join(keysDir, "r2-access-key-id.txt"), "AKIAEXAMPLE\n");
+		writeFileSync(join(keysDir, "r2-secret-access-key.txt"), "secret\n");
+		writeFileSync(join(keysDir, "r2-account-id.txt"), "account\n");
+
+		const config = resolveLogSinkConfig({ env: {}, keysDir });
+		expect(config.transports).toHaveLength(1);
+		expect(config.transports[0].name).toBe("r2");
+	});
+
+	test("auto mode picks up an explicit webhook url", () => {
+		const config = resolveLogSinkConfig({
+			env: { PI_LOG_WEBHOOK_URL: "http://127.0.0.1:8443/api/logs" },
+			keysDir: tempDir(),
+		});
+		expect(config.transports).toHaveLength(1);
+		expect(config.transports[0].name).toBe("webhook");
+	});
+
+	test("r2+webhook keeps R2 as the first transport", () => {
+		const keysDir = tempDir();
+		writeFileSync(join(keysDir, "r2-bucket-name.txt"), "logs-bucket\n");
+		writeFileSync(join(keysDir, "r2-access-key-id.txt"), "AKIAEXAMPLE\n");
+		writeFileSync(join(keysDir, "r2-secret-access-key.txt"), "secret\n");
+		writeFileSync(join(keysDir, "r2-endpoint.txt"), "https://example.r2.cloudflarestorage.com\n");
+
+		const config = resolveLogSinkConfig({
+			env: { PI_LOG_SINK: "r2+webhook", PI_LOG_WEBHOOK_URL: "http://127.0.0.1:8443/api/logs" },
+			keysDir,
+		});
+		expect(config.transports.map((transport) => transport.name)).toEqual(["r2", "webhook"]);
+	});
+
+	test("r2 without credentials is skipped and reported", () => {
+		const config = resolveLogSinkConfig({ env: { PI_LOG_SINK: "r2" }, keysDir: tempDir() });
+		expect(config.transports).toHaveLength(0);
+		expect(config.notes.join(" ")).toContain("credentials are incomplete");
+	});
+
+	test("sampling and buffer settings come from the environment", () => {
+		const config = resolveLogSinkConfig({
+			env: {
+				PI_LOG_LEVEL: "warn",
+				PI_LOG_SAMPLE_RATE: "0.5",
+				PI_LOG_RATE_LIMIT: "5",
+				PI_LOG_BUFFER_SIZE: "42",
+				PI_LOG_BATCH_SIZE: "7",
+				PI_LOG_FLUSH_INTERVAL_MS: "1000",
+			},
+			keysDir: tempDir(),
+		});
+
+		expect(config.sampling.minLevel).toBe("warn");
+		expect(config.sampling.sampleRate).toBe(0.5);
+		expect(config.sampling.rateLimitPerMinute).toBe(5);
+		expect(config.buffer.maxSize).toBe(42);
+		expect(config.buffer.maxBatchSize).toBe(7);
+		expect(config.flushIntervalMs).toBe(1000);
+	});
+});