pi-harness-runtime 1.1.394 → 1.1.396

package/packages/logging/dist/transports/r2.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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 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 declare function r2ObjectKey(prefix: string, batch: LogBatch): string;
+export declare function createR2Transport(options: R2TransportOptions): LogTransport;
+//# sourceMappingURL=r2.d.ts.map

package/packages/logging/dist/transports/r2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"r2.d.ts","sourceRoot":"","sources":["../../src/transports/r2.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE1D,MAAM,WAAW,kBAAkB;IAClC,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,IAAI,CAAC,EAAE,OAAO,CAAC;CACf;AAED,yDAAyD;AACzD,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,MAAM,CAOnE;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,YAAY,CA4C3E"}

package/packages/logging/dist/transports/r2.js

@@ -0,0 +1,60 @@
+/**
+ * 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";
+/** Build the date-partitioned object key for a batch. */
+export function r2ObjectKey(prefix, batch) {
+    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) {
+    const prefix = options.prefix ?? "logs/harness";
+    const region = options.region ?? "auto";
+    const gzip = options.gzip ?? true;
+    return {
+        name: "r2",
+        async send(batch) {
+            if (batch.records.length === 0)
+                return;
+            let 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();
+        },
+    };
+}
+//# sourceMappingURL=r2.js.map

package/packages/logging/dist/transports/r2.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"r2.js","sourceRoot":"","sources":["../../src/transports/r2.ts"],"names":[],"mappings":"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"}

package/packages/logging/dist/transports/webhook.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 { 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 declare function createWebhookTransport(options: WebhookTransportOptions): LogTransport;
+//# sourceMappingURL=webhook.d.ts.map

package/packages/logging/dist/transports/webhook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.d.ts","sourceRoot":"","sources":["../../src/transports/webhook.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAY,YAAY,EAAE,MAAM,aAAa,CAAC;AAE1D,MAAM,WAAW,uBAAuB;IACvC,uCAAuC;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,6BAA6B;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qBAAqB;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CACzB;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,uBAAuB,GAAG,YAAY,CA8BrF"}

package/packages/logging/dist/transports/webhook.js

@@ -0,0 +1,37 @@
+/**
+ * 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.
+ */
+export function createWebhookTransport(options) {
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    return {
+        name: "webhook",
+        async send(batch) {
+            if (batch.records.length === 0)
+                return;
+            if (typeof fetchImpl !== "function") {
+                throw new Error("Webhook transport requires a fetch implementation");
+            }
+            const headers = {
+                "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}`);
+            }
+        },
+    };
+}
+//# sourceMappingURL=webhook.js.map

package/packages/logging/dist/transports/webhook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.js","sourceRoot":"","sources":["../../src/transports/webhook.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAiBH,MAAM,UAAU,sBAAsB,CAAC,OAAgC;IACtE,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,MAAM,CAAC;IAC9C,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,UAAU,CAAC,KAAK,CAAC;IAExD,OAAO;QACN,IAAI,EAAE,SAAS;QACf,KAAK,CAAC,IAAI,CAAC,KAAe;YACzB,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO;YACvC,IAAI,OAAO,SAAS,KAAK,UAAU,EAAE,CAAC;gBACrC,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;YACtE,CAAC;YAED,MAAM,OAAO,GAA2B;gBACvC,cAAc,EAAE,kBAAkB;gBAClC,GAAG,OAAO,CAAC,OAAO;aAClB,CAAC;YACF,IAAI,OAAO,CAAC,KAAK;gBAAE,OAAO,CAAC,aAAa,GAAG,UAAU,OAAO,CAAC,KAAK,EAAE,CAAC;YAErE,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC,GAAG,EAAE;gBAC7C,MAAM,EAAE,MAAM;gBACd,OAAO;gBACP,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;gBAC3B,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,SAAS,CAAC;aACtC,CAAC,CAAC;YAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBAClB,MAAM,IAAI,KAAK,CAAC,sCAAsC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;YAC1E,CAAC;QACF,CAAC;KACD,CAAC;AACH,CAAC"}

package/packages/logging/dist/types.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 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 declare const LOG_LEVEL_SEVERITY: Record<LogLevel, number>;
+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>;
+}
+//# sourceMappingURL=types.d.ts.map

package/packages/logging/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3D,qEAAqE;AACrE,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAKvD,CAAC;AAEF,MAAM,WAAW,YAAY;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED,sCAAsC;AACtC,MAAM,WAAW,SAAS;IACzB,uCAAuC;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,QAAQ,CAAC;IAChB,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,YAAY,CAAC;CACrB;AAED,4CAA4C;AAC5C,MAAM,WAAW,QAAQ;IACxB,KAAK,EAAE,QAAQ,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,sEAAsE;IACtE,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,+DAA+D;AAC/D,MAAM,WAAW,QAAQ;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,SAAS,EAAE,CAAC;CACrB;AAED,8DAA8D;AAC9D,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,UAAU;IAC1B,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B"}

package/packages/logging/dist/types.js

@@ -0,0 +1,19 @@
+/**
+ * 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.
+ */
+/** Severity order used by the sampler and the buffer drop policy. */
+export const LOG_LEVEL_SEVERITY = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+};
+//# sourceMappingURL=types.js.map

package/packages/logging/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,qEAAqE;AACrE,MAAM,CAAC,MAAM,kBAAkB,GAA6B;IAC3D,KAAK,EAAE,EAAE;IACT,IAAI,EAAE,EAAE;IACR,IAAI,EAAE,EAAE;IACR,KAAK,EAAE,EAAE;CACT,CAAC"}

package/packages/logging/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@pi-harness/logging",
+  "version": "1.1.396",
+  "type": "module",
+  "description": "Centralized structured application logging with buffered Cloudflare R2 and webhook transports",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "bun test"
+  },
+  "keywords": [
+    "logging",
+    "observability",
+    "r2",
+    "cloudflare"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^26.6.4",
+    "typescript": "^5.7.2"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-s3": ">=3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@aws-sdk/client-s3": {
+      "optional": true
+    }
+  }
+}

package/packages/logging/src/buffer.ts

@@ -0,0 +1,77 @@
+/**
+ * In-memory batching buffer for the centralized log pipeline.
+ *
+ * The buffer is bounded on purpose: a logging subsystem must never be the
+ * reason a process runs out of memory. When the buffer is full the LEAST
+ * severe record is dropped first, and the drop is counted so the loss is
+ * visible instead of silent.
+ */
+
+import { LOG_LEVEL_SEVERITY, type LogRecord } from "./types.js";
+
+export interface LogBufferOptions {
+	/** Maximum number of records held in memory. Default 1000. */
+	maxSize?: number;
+	/** Maximum number of records per batch. Default 100. */
+	maxBatchSize?: number;
+}
+
+export class LogBuffer {
+	private readonly records: LogRecord[] = [];
+	private readonly maxSize: number;
+	private readonly maxBatchSize: number;
+	private droppedCount = 0;
+
+	constructor(options: LogBufferOptions = {}) {
+		this.maxSize = Math.max(1, options.maxSize ?? 1000);
+		this.maxBatchSize = Math.max(1, options.maxBatchSize ?? 100);
+	}
+
+	get size(): number {
+		return this.records.length;
+	}
+
+	get dropped(): number {
+		return this.droppedCount;
+	}
+
+	get batchSize(): number {
+		return this.maxBatchSize;
+	}
+
+	push(record: LogRecord): void {
+		if (this.records.length >= this.maxSize) {
+			this.dropLowestSeverity();
+		}
+		this.records.push(record);
+	}
+
+	/** Remove and return up to `maxBatchSize` of the oldest records. */
+	takeBatch(maxBatchSize: number = this.maxBatchSize): LogRecord[] {
+		const count = Math.min(Math.max(0, maxBatchSize), this.records.length);
+		return this.records.splice(0, count);
+	}
+
+	/** Peek without removing (used by the synchronous exit path). */
+	peekAll(): LogRecord[] {
+		return [...this.records];
+	}
+
+	clear(): void {
+		this.records.length = 0;
+	}
+
+	private dropLowestSeverity(): void {
+		let index = 0;
+		let lowest = Number.POSITIVE_INFINITY;
+		for (let i = 0; i < this.records.length; i++) {
+			const severity = LOG_LEVEL_SEVERITY[this.records[i].level];
+			if (severity < lowest) {
+				lowest = severity;
+				index = i;
+			}
+		}
+		this.records.splice(index, 1);
+		this.droppedCount++;
+	}
+}

package/packages/logging/src/config.ts

@@ -0,0 +1,163 @@
+/**
+ * Configuration for the centralized log pipeline.
+ *
+ * Resolution order for credentials:
+ *   environment variable -> key file in ~/.pi-harness-runtime/keys
+ *
+ * Secrets are never hardcoded here. A key file that is missing simply means
+ * the corresponding transport is not configured.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { createR2Transport } from "./transports/r2.js";
+import { createWebhookTransport } from "./transports/webhook.js";
+import type { LogBufferOptions } from "./buffer.js";
+import type { SamplingPolicy } from "./sampler.js";
+import type { LogTransport } from "./types.js";
+
+export type LogSinkMode = "off" | "auto" | "r2" | "webhook" | "r2+webhook";
+
+export interface LogSinkConfig {
+	/** False when nothing should be shipped (no transports, no spool). */
+	enabled: boolean;
+	/** Application name reported with every batch. */
+	app: string;
+	/** Transports in delivery priority order. */
+	transports: LogTransport[];
+	/** Directory of the local spool (undefined when logging is off). */
+	spoolDir?: string;
+	sampling: Partial<SamplingPolicy>;
+	buffer: LogBufferOptions;
+	flushIntervalMs: number;
+	/** Human readable notes about what was enabled and why. */
+	notes: string[];
+}
+
+export interface ResolveConfigOptions {
+	env?: Record<string, string | undefined>;
+	/** Directory holding the credential key files. */
+	keysDir?: string;
+}
+
+function readKeyFile(keysDir: string, name: string): string | undefined {
+	const file = join(keysDir, name);
+	if (!existsSync(file)) return undefined;
+	const value = readFileSync(file, "utf8").trim();
+	return value.length > 0 ? value : undefined;
+}
+
+function readNumber(
+	env: Record<string, string | undefined>,
+	key: string,
+	fallback: number,
+): number {
+	const raw = env[key];
+	if (!raw) return fallback;
+	const parsed = Number(raw);
+	return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+export function defaultKeysDir(): string {
+	return join(homedir(), ".pi-harness-runtime", "keys");
+}
+
+export function defaultSpoolDir(): string {
+	return join(homedir(), ".pi-harness-runtime", "logs", "spool");
+}
+
+/**
+ * Build the log sink configuration from the environment and the key files.
+ */
+export function resolveLogSinkConfig(options: ResolveConfigOptions = {}): LogSinkConfig {
+	const env = options.env ?? process.env;
+	const keysDir = options.keysDir ?? defaultKeysDir();
+	const mode = (env.PI_LOG_SINK ?? "auto") as LogSinkMode;
+	const notes: string[] = [];
+
+	if (mode === "off") {
+		return {
+			enabled: false,
+			app: env.PI_LOG_APP ?? "pi-harness",
+			transports: [],
+			sampling: {},
+			buffer: {},
+			flushIntervalMs: 0,
+			notes: ["logging disabled by PI_LOG_SINK=off"],
+		};
+	}
+
+	const transports: LogTransport[] = [];
+
+	const bucket = env.PI_LOG_R2_BUCKET ?? readKeyFile(keysDir, "r2-bucket-name.txt");
+	const accessKeyId =
+		env.PI_LOG_R2_ACCESS_KEY_ID ?? readKeyFile(keysDir, "r2-access-key-id.txt");
+	const secretAccessKey =
+		env.PI_LOG_R2_SECRET_ACCESS_KEY ?? readKeyFile(keysDir, "r2-secret-access-key.txt");
+	const accountId = env.PI_LOG_R2_ACCOUNT_ID ?? readKeyFile(keysDir, "r2-account-id.txt");
+	const endpoint =
+		env.PI_LOG_R2_ENDPOINT ??
+		readKeyFile(keysDir, "r2-endpoint.txt") ??
+		(accountId ? `https://${accountId}.r2.cloudflarestorage.com` : undefined);
+
+	const r2Ready = Boolean(bucket && accessKeyId && secretAccessKey && endpoint);
+	const wantR2 = mode === "r2" || mode === "r2+webhook" || (mode === "auto" && r2Ready);
+
+	if (wantR2) {
+		if (r2Ready) {
+			transports.push(
+				createR2Transport({
+					bucket: bucket as string,
+					endpoint: endpoint as string,
+					accessKeyId: accessKeyId as string,
+					secretAccessKey: secretAccessKey as string,
+					prefix: env.PI_LOG_R2_PREFIX ?? "logs/harness",
+				}),
+			);
+			notes.push(`r2 enabled (bucket ${bucket})`);
+		} else {
+			notes.push("r2 requested but credentials are incomplete - transport skipped");
+		}
+	}
+
+	const webhookUrl = env.PI_LOG_WEBHOOK_URL;
+	const wantWebhook =
+		mode === "webhook" || mode === "r2+webhook" || (mode === "auto" && Boolean(webhookUrl));
+
+	if (wantWebhook) {
+		if (webhookUrl) {
+			transports.push(
+				createWebhookTransport({
+					url: webhookUrl,
+					token: env.PI_LOG_WEBHOOK_TOKEN,
+				}),
+			);
+			notes.push(`webhook enabled (${webhookUrl})`);
+		} else {
+			notes.push("webhook requested but PI_LOG_WEBHOOK_URL is not set - transport skipped");
+		}
+	}
+
+	if (transports.length === 0) {
+		notes.push("no transport configured - logs stay local");
+	}
+
+	return {
+		enabled: true,
+		app: env.PI_LOG_APP ?? "pi-harness",
+		transports,
+		spoolDir: env.PI_LOG_SPOOL_DIR ?? defaultSpoolDir(),
+		sampling: {
+			minLevel: (env.PI_LOG_LEVEL as SamplingPolicy["minLevel"]) ?? "info",
+			sampleRate: readNumber(env, "PI_LOG_SAMPLE_RATE", 0.1),
+			rateLimitPerMinute: readNumber(env, "PI_LOG_RATE_LIMIT", 60),
+		},
+		buffer: {
+			maxSize: readNumber(env, "PI_LOG_BUFFER_SIZE", 1000),
+			maxBatchSize: readNumber(env, "PI_LOG_BATCH_SIZE", 100),
+		},
+		flushIntervalMs: readNumber(env, "PI_LOG_FLUSH_INTERVAL_MS", 15_000),
+		notes,
+	};
+}

package/packages/logging/src/index.ts

@@ -0,0 +1,87 @@
+/**
+ * @pi-harness/logging - centralized application logging.
+ *
+ * One structured record format, one redaction policy, one delivery path:
+ *
+ *   producer -> redactor -> sampler -> buffer -> R2 / webhook -> local spool
+ *
+ * The transport order is deliberate: R2 keeps the durable archive, the
+ * webhook server provides the live path, and the local spool is the
+ * fallback that keeps data when both are unavailable.
+ */
+
+// --- Types -----------------------------------------------------------------
+
+export { LOG_LEVEL_SEVERITY } from "./types.js";
+export type {
+	FlushStats,
+	LogBatch,
+	LogErrorInfo,
+	LogInput,
+	LogLevel,
+	LogRecord,
+	LogTransport,
+} from "./types.js";
+
+// --- Redaction -------------------------------------------------------------
+
+export {
+	isSecretKey,
+	isSensitiveValueKey,
+	redactFields,
+	redactText,
+	redactValue,
+	splitKeyTokens,
+} from "./redact.js";
+export type { JsonValue, RedactionOptions } from "./redact.js";
+
+// --- Sampling --------------------------------------------------------------
+
+export { DEFAULT_SAMPLING_POLICY, LogSampler } from "./sampler.js";
+export type { SamplingPolicy } from "./sampler.js";
+
+// --- Buffering -------------------------------------------------------------
+
+export { LogBuffer } from "./buffer.js";
+export type { LogBufferOptions } from "./buffer.js";
+
+// --- Local spool -----------------------------------------------------------
+
+export { LogSpool } from "./spool.js";
+export type { LogSpoolOptions } from "./spool.js";
+
+// --- Transports ------------------------------------------------------------
+
+export { createR2Transport, r2ObjectKey } from "./transports/r2.js";
+export type { R2TransportOptions } from "./transports/r2.js";
+export { createWebhookTransport } from "./transports/webhook.js";
+export type { WebhookTransportOptions } from "./transports/webhook.js";
+
+// --- Shipper ---------------------------------------------------------------
+
+export { LogShipper } from "./shipper.js";
+export type { LogShipperOptions } from "./shipper.js";
+
+// --- Process wide singleton -------------------------------------------------
+
+export {
+	centralDebug,
+	centralError,
+	centralInfo,
+	centralLog,
+	centralWarn,
+	getCentralLogConfig,
+	getCentralShipper,
+	initCentralLogging,
+	shutdownCentralLogging,
+} from "./singleton.js";
+export type { InitCentralLoggingOptions } from "./singleton.js";
+
+// --- Configuration ---------------------------------------------------------
+
+export {
+	defaultKeysDir,
+	defaultSpoolDir,
+	resolveLogSinkConfig,
+} from "./config.js";
+export type { LogSinkConfig, LogSinkMode, ResolveConfigOptions } from "./config.js";