pi-harness-runtime 1.1.394 → 1.1.396

package/packages/logging/dist/config.js

@@ -0,0 +1,114 @@
+/**
+ * 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";
+function readKeyFile(keysDir, name) {
+    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, key, fallback) {
+    const raw = env[key];
+    if (!raw)
+        return fallback;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) ? parsed : fallback;
+}
+export function defaultKeysDir() {
+    return join(homedir(), ".pi-harness-runtime", "keys");
+}
+export function defaultSpoolDir() {
+    return join(homedir(), ".pi-harness-runtime", "logs", "spool");
+}
+/**
+ * Build the log sink configuration from the environment and the key files.
+ */
+export function resolveLogSinkConfig(options = {}) {
+    const env = options.env ?? process.env;
+    const keysDir = options.keysDir ?? defaultKeysDir();
+    const mode = (env.PI_LOG_SINK ?? "auto");
+    const notes = [];
+    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 = [];
+    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,
+                endpoint: endpoint,
+                accessKeyId: accessKeyId,
+                secretAccessKey: secretAccessKey,
+                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 ?? "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,
+    };
+}
+//# sourceMappingURL=config.js.map

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

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

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

@@ -0,0 +1,32 @@
+/**
+ * @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.
+ */
+export { LOG_LEVEL_SEVERITY } from "./types.js";
+export type { FlushStats, LogBatch, LogErrorInfo, LogInput, LogLevel, LogRecord, LogTransport, } from "./types.js";
+export { isSecretKey, isSensitiveValueKey, redactFields, redactText, redactValue, splitKeyTokens, } from "./redact.js";
+export type { JsonValue, RedactionOptions } from "./redact.js";
+export { DEFAULT_SAMPLING_POLICY, LogSampler } from "./sampler.js";
+export type { SamplingPolicy } from "./sampler.js";
+export { LogBuffer } from "./buffer.js";
+export type { LogBufferOptions } from "./buffer.js";
+export { LogSpool } from "./spool.js";
+export type { LogSpoolOptions } from "./spool.js";
+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";
+export { LogShipper } from "./shipper.js";
+export type { LogShipperOptions } from "./shipper.js";
+export { centralDebug, centralError, centralInfo, centralLog, centralWarn, getCentralLogConfig, getCentralShipper, initCentralLogging, shutdownCentralLogging, } from "./singleton.js";
+export type { InitCentralLoggingOptions } from "./singleton.js";
+export { defaultKeysDir, defaultSpoolDir, resolveLogSinkConfig, } from "./config.js";
+export type { LogSinkConfig, LogSinkMode, ResolveConfigOptions } from "./config.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,YAAY,EACX,UAAU,EACV,QAAQ,EACR,YAAY,EACZ,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,YAAY,GACZ,MAAM,YAAY,CAAC;AAIpB,OAAO,EACN,WAAW,EACX,mBAAmB,EACnB,YAAY,EACZ,UAAU,EACV,WAAW,EACX,cAAc,GACd,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAI/D,OAAO,EAAE,uBAAuB,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AACnE,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAInD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAIpD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAIlD,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACpE,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACjE,YAAY,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAIvE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAItD,OAAO,EACN,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,UAAU,EACV,WAAW,EACX,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,sBAAsB,GACtB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAIhE,OAAO,EACN,cAAc,EACd,eAAe,EACf,oBAAoB,GACpB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC"}

package/packages/logging/dist/index.js

@@ -0,0 +1,31 @@
+/**
+ * @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";
+// --- Redaction -------------------------------------------------------------
+export { isSecretKey, isSensitiveValueKey, redactFields, redactText, redactValue, splitKeyTokens, } from "./redact.js";
+// --- Sampling --------------------------------------------------------------
+export { DEFAULT_SAMPLING_POLICY, LogSampler } from "./sampler.js";
+// --- Buffering -------------------------------------------------------------
+export { LogBuffer } from "./buffer.js";
+// --- Local spool -----------------------------------------------------------
+export { LogSpool } from "./spool.js";
+// --- Transports ------------------------------------------------------------
+export { createR2Transport, r2ObjectKey } from "./transports/r2.js";
+export { createWebhookTransport } from "./transports/webhook.js";
+// --- Shipper ---------------------------------------------------------------
+export { LogShipper } from "./shipper.js";
+// --- Process wide singleton -------------------------------------------------
+export { centralDebug, centralError, centralInfo, centralLog, centralWarn, getCentralLogConfig, getCentralShipper, initCentralLogging, shutdownCentralLogging, } from "./singleton.js";
+// --- Configuration ---------------------------------------------------------
+export { defaultKeysDir, defaultSpoolDir, resolveLogSinkConfig, } from "./config.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,8EAA8E;AAE9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAWhD,8EAA8E;AAE9E,OAAO,EACN,WAAW,EACX,mBAAmB,EACnB,YAAY,EACZ,UAAU,EACV,WAAW,EACX,cAAc,GACd,MAAM,aAAa,CAAC;AAGrB,8EAA8E;AAE9E,OAAO,EAAE,uBAAuB,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAGnE,8EAA8E;AAE9E,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC,8EAA8E;AAE9E,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGtC,8EAA8E;AAE9E,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAGjE,8EAA8E;AAE9E,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG1C,+EAA+E;AAE/E,OAAO,EACN,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,UAAU,EACV,WAAW,EACX,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,sBAAsB,GACtB,MAAM,gBAAgB,CAAC;AAGxB,8EAA8E;AAE9E,OAAO,EACN,cAAc,EACd,eAAe,EACf,oBAAoB,GACpB,MAAM,aAAa,CAAC"}

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

@@ -0,0 +1,43 @@
+/**
+ * Secret redaction for log records.
+ *
+ * Two independent layers, because either one alone leaks:
+ *   1. Key based - a field named `apiKey` is replaced wholesale.
+ *   2. Value based - a secret embedded in free text (`Bearer abc...`) is
+ *      replaced even when the key name is innocuous.
+ *
+ * The rules are intentionally conservative: over-redacting a log line is
+ * cheap, leaking a credential is not.
+ */
+/**
+ * The redacted shape of a log value. Everything that leaves the process is
+ * JSON, so the redactor is typed against JSON instead of `unknown`.
+ */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export interface RedactionOptions {
+    /** Longest string kept verbatim before truncation. Default 2000. */
+    maxStringLength?: number;
+    /** Maximum nesting depth kept. Default 5. */
+    maxDepth?: number;
+    /** Maximum number of keys kept per object. Default 50. */
+    maxKeys?: number;
+    /** Maximum number of items kept per array. Default 20. */
+    maxArrayItems?: number;
+    /** Placeholder written instead of a redacted value. */
+    placeholder?: string;
+}
+/** Split a key into lowercase tokens (`apiKey` -> `api`, `key`). */
+export declare function splitKeyTokens(key: string): string[];
+/** True when the key itself identifies a secret. */
+export declare function isSecretKey(key: string): boolean;
+/** True when the key holds content that must not be logged verbatim. */
+export declare function isSensitiveValueKey(key: string): boolean;
+/** Replace credential-looking substrings inside a free-text value. */
+export declare function redactText(text: string, placeholder?: string): string;
+/** Redact an arbitrary value (strings, numbers, objects, arrays). */
+export declare function redactValue(value: unknown, options?: RedactionOptions, depth?: number, keyHint?: string): JsonValue;
+/** Redact a flat field bag (the `fields` member of a record). */
+export declare function redactFields(fields: Record<string, unknown> | undefined, options?: RedactionOptions): Record<string, JsonValue> | undefined;
+//# sourceMappingURL=redact.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../src/redact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;GAGG;AACH,MAAM,MAAM,SAAS,GAClB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,EAAE,GACX;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEhC,MAAM,WAAW,gBAAgB;IAChC,oEAAoE;IACpE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uDAAuD;IACvD,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAqFD,oEAAoE;AACpE,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAMpD;AAED,oDAAoD;AACpD,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAYhD;AAED,wEAAwE;AACxE,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAGxD;AAED,sEAAsE;AACtE,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,SAAsB,GAAG,MAAM,CAelF;AAOD,qEAAqE;AACrE,wBAAgB,WAAW,CAC1B,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,gBAAqB,EAC9B,KAAK,SAAI,EACT,OAAO,CAAC,EAAE,MAAM,GACd,SAAS,CAkFX;AAED,iEAAiE;AACjE,wBAAgB,YAAY,CAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC3C,OAAO,GAAE,gBAAqB,GAC5B,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,SAAS,CAGvC"}

package/packages/logging/dist/redact.js

@@ -0,0 +1,220 @@
+/**
+ * Secret redaction for log records.
+ *
+ * Two independent layers, because either one alone leaks:
+ *   1. Key based - a field named `apiKey` is replaced wholesale.
+ *   2. Value based - a secret embedded in free text (`Bearer abc...`) is
+ *      replaced even when the key name is innocuous.
+ *
+ * The rules are intentionally conservative: over-redacting a log line is
+ * cheap, leaking a credential is not.
+ */
+const DEFAULT_PLACEHOLDER = "[REDACTED]";
+/**
+ * Key names that always hold a secret. Matched as a whole token after the
+ * key is split on non-alphanumerics and camelCase boundaries.
+ */
+const SECRET_KEY_TOKENS = new Set([
+    "password",
+    "passwd",
+    "passphrase",
+    "secret",
+    "secrets",
+    "token",
+    "tokens",
+    "apikey",
+    "apisecret",
+    "authorization",
+    "auth",
+    "credential",
+    "credentials",
+    "privatekey",
+    "cookie",
+    "setcookie",
+    "sessionkey",
+    "accesskey",
+    "secretaccesskey",
+    "refreshtoken",
+    "bearertoken",
+    "signature",
+    "otp",
+    "pin",
+    "mfa",
+    "totp",
+]);
+/**
+ * Key names whose VALUE is sensitive even though the key itself is not a
+ * credential: prompts, raw model output and embeddings must never leave the
+ * machine in a log line.
+ */
+const SENSITIVE_VALUE_TOKENS = new Set([
+    "content",
+    "raw",
+    "prompt",
+    "prompts",
+    "messages",
+    "embedding",
+    "embeddings",
+    "vector",
+    "vectors",
+    "body",
+    "chatid",
+    "payload",
+    "transcript",
+]);
+/**
+ * Value patterns that look like credentials wherever they appear.
+ * Order matters: the more specific patterns run first.
+ */
+const SECRET_VALUE_PATTERNS = [
+    // Authorization headers and bearer tokens.
+    /\b(?:bearer|basic)\s+[A-Za-z0-9._~+/=-]{8,}/gi,
+    // JWT.
+    /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{4,}/g,
+    // OpenAI / Anthropic style keys.
+    /\bsk-[A-Za-z0-9_-]{12,}/g,
+    // AWS access key ids.
+    /\bAKIA[0-9A-Z]{12,}/g,
+    // GitHub / Slack / Stripe style tokens.
+    /\bgh[pousr]_[A-Za-z0-9]{16,}/g,
+    /\bxox[baprs]-[A-Za-z0-9-]{10,}/g,
+    // Cloudflare R2 style secret keys (long base64-ish runs).
+    /\b[A-Za-z0-9_-]{40,}\b/g,
+];
+/**
+ * `key = value` assignments of a credential-looking key. The key prefix is
+ * preserved, only the value is replaced.
+ */
+const SECRET_ASSIGNMENT_PATTERN = /\b((?:api[_-]?key|apikey|access[_-]?key|secret[_-]?key|secret|token|password|passwd|authorization)\s*[:=]\s*)("?)([^\s"',;}]{4,})\2/gi;
+/** Split a key into lowercase tokens (`apiKey` -> `api`, `key`). */
+export function splitKeyTokens(key) {
+    return key
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .split(/[^A-Za-z0-9]+/)
+        .filter(Boolean)
+        .map((part) => part.toLowerCase());
+}
+/** True when the key itself identifies a secret. */
+export function isSecretKey(key) {
+    const tokens = splitKeyTokens(key);
+    if (tokens.some((token) => SECRET_KEY_TOKENS.has(token)))
+        return true;
+    // Compound names such as `openaiApiKey` or `r2_secret_access_key`.
+    const joined = tokens.join("");
+    return (joined.includes("apikey") ||
+        joined.includes("secretaccesskey") ||
+        joined.includes("privatekey") ||
+        joined.includes("accesstoken") ||
+        joined.includes("authtoken"));
+}
+/** True when the key holds content that must not be logged verbatim. */
+export function isSensitiveValueKey(key) {
+    const tokens = splitKeyTokens(key);
+    return tokens.some((token) => SENSITIVE_VALUE_TOKENS.has(token));
+}
+/** Replace credential-looking substrings inside a free-text value. */
+export function redactText(text, placeholder = DEFAULT_PLACEHOLDER) {
+    let result = text;
+    for (const pattern of SECRET_VALUE_PATTERNS) {
+        // The regexes are global, so `lastIndex` must be reset per use.
+        pattern.lastIndex = 0;
+        result = result.replace(pattern, placeholder);
+    }
+    // `apiKey=abc` keeps the key name, loses the value. This runs last so a
+    // credential that was already replaced is not matched a second time.
+    SECRET_ASSIGNMENT_PATTERN.lastIndex = 0;
+    result = result.replace(SECRET_ASSIGNMENT_PATTERN, `$1${placeholder}`);
+    return result;
+}
+function truncate(text, maxLength) {
+    if (text.length <= maxLength)
+        return text;
+    return `${text.slice(0, maxLength)}...[truncated:${text.length - maxLength}]`;
+}
+/** Redact an arbitrary value (strings, numbers, objects, arrays). */
+export function redactValue(value, options = {}, depth = 0, keyHint) {
+    const maxStringLength = options.maxStringLength ?? 2000;
+    const maxDepth = options.maxDepth ?? 5;
+    const maxKeys = options.maxKeys ?? 50;
+    const maxArrayItems = options.maxArrayItems ?? 20;
+    const placeholder = options.placeholder ?? DEFAULT_PLACEHOLDER;
+    if (keyHint && isSecretKey(keyHint)) {
+        return placeholder;
+    }
+    if (value === null || value === undefined)
+        return null;
+    switch (typeof value) {
+        case "string":
+            return truncate(redactText(value, placeholder), maxStringLength);
+        case "number":
+        case "boolean":
+            return value;
+        case "bigint":
+            return value.toString();
+        case "function":
+        case "symbol":
+            return `[${typeof value}]`;
+        default:
+            break;
+    }
+    if (value instanceof Date)
+        return value.toISOString();
+    if (value instanceof Error) {
+        const info = {
+            name: value.name,
+            message: redactText(value.message, placeholder),
+        };
+        if (value.stack)
+            info.stack = redactText(value.stack, placeholder);
+        return info;
+    }
+    if (depth >= maxDepth)
+        return "[MAX_DEPTH]";
+    if (Array.isArray(value)) {
+        const items = value.slice(0, maxArrayItems).map((item) => redactValue(item, options, depth + 1));
+        if (value.length > maxArrayItems) {
+            items.push(`[+${value.length - maxArrayItems} more]`);
+        }
+        return items;
+    }
+    if (value instanceof Map) {
+        const out = {};
+        let count = 0;
+        for (const [key, item] of value) {
+            if (count >= maxKeys)
+                break;
+            out[String(key)] = redactValue(item, options, depth + 1, String(key));
+            count++;
+        }
+        return out;
+    }
+    if (value instanceof Set) {
+        return redactValue([...value], options, depth + 1);
+    }
+    const record = value;
+    const out = {};
+    const keys = Object.keys(record);
+    for (const key of keys.slice(0, maxKeys)) {
+        const item = record[key];
+        if (isSecretKey(key)) {
+            out[key] = placeholder;
+            continue;
+        }
+        if (isSensitiveValueKey(key)) {
+            out[key] = placeholder;
+            continue;
+        }
+        out[key] = redactValue(item, options, depth + 1, key);
+    }
+    if (keys.length > maxKeys) {
+        out["[truncatedKeys]"] = keys.length - maxKeys;
+    }
+    return out;
+}
+/** Redact a flat field bag (the `fields` member of a record). */
+export function redactFields(fields, options = {}) {
+    if (!fields)
+        return undefined;
+    return redactValue(fields, options);
+}
+//# sourceMappingURL=redact.js.map

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

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

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

@@ -0,0 +1,37 @@
+/**
+ * Sampling for the centralized log pipeline.
+ *
+ * Sampling protects the transport budget, not the producer: a chatty
+ * component must not be able to flood R2 (or the webhook server) with
+ * debug-level noise.
+ *
+ * Three independent gates:
+ *   1. minimum level  - everything below the configured level is dropped
+ *   2. sample rate    - debug records are kept deterministically per event
+ *   3. rate limit     - a cap per source+event per minute
+ *
+ * Errors bypass the sample rate and the rate limit. Losing an error to
+ * save a request is the wrong trade.
+ */
+import { type LogLevel, type LogRecord } from "./types.js";
+export interface SamplingPolicy {
+    /** Records below this level are dropped. Default "info". */
+    minLevel: LogLevel;
+    /** Fraction of debug records kept, 0..1. Default 0.1. */
+    sampleRate: number;
+    /** Max records per source+event per minute (errors exempt). Default 60. */
+    rateLimitPerMinute: number;
+}
+export declare const DEFAULT_SAMPLING_POLICY: SamplingPolicy;
+export declare class LogSampler {
+    private readonly policy;
+    private readonly counters;
+    constructor(policy?: Partial<SamplingPolicy>);
+    getPolicy(): SamplingPolicy;
+    /** True when the record should be kept. */
+    shouldLog(record: LogRecord, now?: number): boolean;
+    private allowByRateLimit;
+    /** Forget the rate-limit counters (used by tests and by long sessions). */
+    reset(): void;
+}
+//# sourceMappingURL=sampler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sampler.d.ts","sourceRoot":"","sources":["../src/sampler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAsB,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAE/E,MAAM,WAAW,cAAc;IAC9B,4DAA4D;IAC5D,QAAQ,EAAE,QAAQ,CAAC;IACnB,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,kBAAkB,EAAE,MAAM,CAAC;CAC3B;AAED,eAAO,MAAM,uBAAuB,EAAE,cAIrC,CAAC;AAeF,qBAAa,UAAU;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6D;IAEtF,YAAY,MAAM,GAAE,OAAO,CAAC,cAAc,CAAM,EAE/C;IAED,SAAS,IAAI,cAAc,CAE1B;IAED,2CAA2C;IAC3C,SAAS,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,GAAE,MAAmB,GAAG,OAAO,CAa9D;IAED,OAAO,CAAC,gBAAgB;IAkBxB,2EAA2E;IAC3E,KAAK,IAAI,IAAI,CAEZ;CACD"}

package/packages/logging/dist/sampler.js

@@ -0,0 +1,78 @@
+/**
+ * Sampling for the centralized log pipeline.
+ *
+ * Sampling protects the transport budget, not the producer: a chatty
+ * component must not be able to flood R2 (or the webhook server) with
+ * debug-level noise.
+ *
+ * Three independent gates:
+ *   1. minimum level  - everything below the configured level is dropped
+ *   2. sample rate    - debug records are kept deterministically per event
+ *   3. rate limit     - a cap per source+event per minute
+ *
+ * Errors bypass the sample rate and the rate limit. Losing an error to
+ * save a request is the wrong trade.
+ */
+import { LOG_LEVEL_SEVERITY } from "./types.js";
+export const DEFAULT_SAMPLING_POLICY = {
+    minLevel: "info",
+    sampleRate: 0.1,
+    rateLimitPerMinute: 60,
+};
+/**
+ * Stable hash so the same event keeps the same decision across restarts -
+ * a debug event is either always sampled or never, never randomly.
+ */
+function stableHash(input) {
+    let hash = 2166136261;
+    for (let i = 0; i < input.length; i++) {
+        hash ^= input.charCodeAt(i);
+        hash = Math.imul(hash, 16777619);
+    }
+    return (hash >>> 0) / 0xffffffff;
+}
+export class LogSampler {
+    policy;
+    counters = new Map();
+    constructor(policy = {}) {
+        this.policy = { ...DEFAULT_SAMPLING_POLICY, ...policy };
+    }
+    getPolicy() {
+        return { ...this.policy };
+    }
+    /** True when the record should be kept. */
+    shouldLog(record, now = Date.now()) {
+        if (LOG_LEVEL_SEVERITY[record.level] < LOG_LEVEL_SEVERITY[this.policy.minLevel]) {
+            return false;
+        }
+        if (record.level === "error")
+            return true;
+        if (record.level === "debug") {
+            const bucket = stableHash(`${record.source}:${record.event}`);
+            if (bucket >= this.policy.sampleRate)
+                return false;
+        }
+        return this.allowByRateLimit(record, now);
+    }
+    allowByRateLimit(record, now) {
+        const limit = this.policy.rateLimitPerMinute;
+        if (limit <= 0)
+            return true;
+        const key = `${record.source}:${record.event}`;
+        const windowStart = Math.floor(now / 60_000) * 60_000;
+        const entry = this.counters.get(key);
+        if (!entry || entry.windowStart !== windowStart) {
+            this.counters.set(key, { windowStart, count: 1 });
+            return true;
+        }
+        if (entry.count >= limit)
+            return false;
+        entry.count++;
+        return true;
+    }
+    /** Forget the rate-limit counters (used by tests and by long sessions). */
+    reset() {
+        this.counters.clear();
+    }
+}
+//# sourceMappingURL=sampler.js.map

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

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