@centerforagenticai/pi-multi-account 0.1.1

package/src/diagnostic-store.ts

@@ -0,0 +1,276 @@
+import {
+	appendFileSync,
+	chmodSync,
+	mkdirSync,
+	readFileSync,
+	renameSync,
+	statSync,
+	unlinkSync,
+	writeFileSync,
+} from "node:fs";
+import { randomUUID } from "node:crypto";
+import { dirname, join } from "node:path";
+import {
+	sanitizeDiagnosticText,
+	sanitizeForJson,
+	type DiagnosticEvent,
+	type DiagnosticLevel,
+	type DiagnosticPersistence,
+} from "./diagnostics.js";
+import { acquireMachineLease } from "./machine-lease.js";
+
+export const DEFAULT_DIAGNOSTIC_MAX_BYTES = 1024 * 1024;
+const MAX_DIAGNOSTIC_RECORD_BYTES = 64 * 1024;
+const MAX_PERSISTED_FIELDS = 64;
+const DIAGNOSTIC_LEASE_TTL_MS = 5_000;
+const LEVELS = new Set<DiagnosticLevel>(["info", "warning", "error"]);
+
+export interface DiagnosticStorePaths {
+	readonly path: string;
+	readonly lockPath: string;
+}
+
+export function defaultDiagnosticStorePaths(): DiagnosticStorePaths {
+	const agentDir =
+		process.env.PI_CODING_AGENT_DIR ??
+		join(process.env.HOME ?? ".", ".pi", "agent");
+	// Package storage identity stays decoupled from the logical provider ID.
+	const directory = join(agentDir, "pi-multi-account");
+	return {
+		path: join(directory, "diagnostics.ndjson"),
+		lockPath: join(directory, "diagnostics.ndjson.lock"),
+	};
+}
+
+function completePrefixLength(raw: string): number {
+	return raw.endsWith("\n") ? raw.length : raw.lastIndexOf("\n") + 1;
+}
+
+function validTimestamp(value: unknown): value is number {
+	return (
+		typeof value === "number" &&
+		Number.isSafeInteger(value) &&
+		value >= 0
+	);
+}
+
+function projectFields(value: unknown): Readonly<Record<string, string>> | undefined {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		return undefined;
+	}
+	const sanitized = sanitizeForJson(value);
+	if (typeof sanitized !== "object" || sanitized === null || Array.isArray(sanitized)) {
+		return undefined;
+	}
+	const fields: Record<string, string> = {};
+	for (const [key, fieldValue] of Object.entries(sanitized).slice(
+		0,
+		MAX_PERSISTED_FIELDS,
+	)) {
+		if (typeof fieldValue !== "string") continue;
+		fields[sanitizeDiagnosticText(key)] = sanitizeDiagnosticText(fieldValue);
+	}
+	return fields;
+}
+
+function projectEvent(value: unknown): DiagnosticEvent | undefined {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		return undefined;
+	}
+	const candidate = value as Record<string, unknown>;
+	const allowed = new Set(["timestampMs", "level", "category", "message", "fields"]);
+	if (Object.keys(candidate).some((key) => !allowed.has(key))) return undefined;
+	if (!validTimestamp(candidate.timestampMs)) return undefined;
+	if (typeof candidate.level !== "string" || !LEVELS.has(candidate.level as DiagnosticLevel)) {
+		return undefined;
+	}
+	const fields = projectFields(candidate.fields);
+	if (fields === undefined) return undefined;
+	return {
+		timestampMs: candidate.timestampMs,
+		level: candidate.level as DiagnosticLevel,
+		category: sanitizeDiagnosticText(candidate.category),
+		message: sanitizeDiagnosticText(candidate.message),
+		fields,
+	};
+}
+
+function parseCompleteEvents(raw: string): readonly DiagnosticEvent[] {
+	const prefix = raw.slice(0, completePrefixLength(raw));
+	const events: DiagnosticEvent[] = [];
+	for (const line of prefix.split("\n")) {
+		if (!line.trim()) continue;
+		try {
+			const event = projectEvent(JSON.parse(line));
+			if (event !== undefined) events.push(event);
+		} catch {
+			// A malformed or torn record is isolated from later complete records.
+		}
+	}
+	return events;
+}
+
+function newestLinesWithin(
+	events: readonly DiagnosticEvent[],
+	budgetBytes: number,
+): string {
+	const retained: string[] = [];
+	let used = 0;
+	for (let index = events.length - 1; index >= 0; index -= 1) {
+		const line = `${JSON.stringify(events[index])}\n`;
+		const bytes = Buffer.byteLength(line, "utf8");
+		if (bytes > budgetBytes - used) break;
+		retained.push(line);
+		used += bytes;
+	}
+	return retained.reverse().join("");
+}
+
+/** Machine-global, credential-free, bounded diagnostic event history. */
+export class DiagnosticStore implements DiagnosticPersistence {
+	readonly #path: string;
+	readonly #lockPath: string;
+	readonly #maxBytes: number;
+	readonly #beforeCompactionRename: (() => void) | undefined;
+
+	constructor(options: {
+		readonly path?: string;
+		readonly lockPath?: string;
+		readonly maxBytes?: number;
+		/** Test seam for a peer append immediately before the stable-tail sample. */
+		readonly beforeCompactionRename?: () => void;
+	} = {}) {
+		const defaults = defaultDiagnosticStorePaths();
+		this.#path = options.path ?? defaults.path;
+		this.#lockPath = options.lockPath ?? defaults.lockPath;
+		this.#maxBytes = options.maxBytes ?? DEFAULT_DIAGNOSTIC_MAX_BYTES;
+		this.#beforeCompactionRename = options.beforeCompactionRename;
+		if (
+			!Number.isSafeInteger(this.#maxBytes) ||
+			this.#maxBytes < 1_024 ||
+			this.#maxBytes > 64 * 1024 * 1024
+		) {
+			throw new RangeError("maxBytes must be an integer from 1024 through 67108864.");
+		}
+	}
+
+	path(): string {
+		return this.#path;
+	}
+
+	readRecent(limit: number): readonly DiagnosticEvent[] {
+		const safeLimit = Number.isSafeInteger(limit)
+			? Math.max(0, Math.min(limit, 1_000))
+			: 100;
+		if (safeLimit === 0) return [];
+		try {
+			return parseCompleteEvents(readFileSync(this.#path, "utf8")).slice(-safeLimit);
+		} catch {
+			return [];
+		}
+	}
+
+	append(event: DiagnosticEvent): boolean {
+		try {
+			const projected = projectEvent(event);
+			if (projected === undefined) return false;
+			const line = `${JSON.stringify(projected)}\n`;
+			if (Buffer.byteLength(line, "utf8") > MAX_DIAGNOSTIC_RECORD_BYTES) {
+				return false;
+			}
+			const directory = dirname(this.#path);
+			mkdirSync(directory, { recursive: true, mode: 0o700 });
+			chmodSync(directory, 0o700);
+			let separator = "";
+			try {
+				const current = readFileSync(this.#path, "utf8");
+				if (current.length > 0 && !current.endsWith("\n")) separator = "\n";
+			} catch {
+				// appendFileSync creates a missing file below.
+			}
+			appendFileSync(this.#path, `${separator}${line}`, {
+				encoding: "utf8",
+				mode: 0o600,
+			});
+			chmodSync(this.#path, 0o600);
+			this.#compactIfNeeded();
+			return true;
+		} catch {
+			return false;
+		}
+	}
+
+	#compactIfNeeded(): boolean {
+		try {
+			if (statSync(this.#path).size <= this.#maxBytes) return false;
+		} catch {
+			return false;
+		}
+		let lease: ReturnType<typeof acquireMachineLease>;
+		try {
+			lease = acquireMachineLease({
+				lockPath: this.#lockPath,
+				ttlMs: DIAGNOSTIC_LEASE_TTL_MS,
+				// A wedged lock would otherwise stop compaction and let the
+				// diagnostics log grow past its bound forever.
+				reclaimMalformed: true,
+			});
+		} catch {
+			return false;
+		}
+		if (lease === undefined) return false;
+		let temporaryPath: string | undefined;
+		try {
+			if (!lease.renew()) return false;
+			const initialRaw = readFileSync(this.#path, "utf8");
+			const prefixLength = completePrefixLength(initialRaw);
+			const completePrefix = initialRaw.slice(0, prefixLength);
+			const events = parseCompleteEvents(completePrefix);
+			this.#beforeCompactionRename?.();
+
+			let tail: string | undefined;
+			for (let snapshot = 0; snapshot < 3; snapshot += 1) {
+				const before = statSync(this.#path);
+				const latestRaw = readFileSync(this.#path, "utf8");
+				const after = statSync(this.#path);
+				if (
+					before.dev !== after.dev ||
+					before.ino !== after.ino ||
+					before.size !== after.size
+				) {
+					continue;
+				}
+				if (!latestRaw.startsWith(completePrefix)) return false;
+				tail = latestRaw.slice(prefixLength);
+				break;
+			}
+			if (tail === undefined) return false;
+			const tailBytes = Buffer.byteLength(tail, "utf8");
+			if (tailBytes > this.#maxBytes) return false;
+			const targetBytes = Math.min(
+				Math.floor(this.#maxBytes / 2),
+				this.#maxBytes - tailBytes,
+			);
+			const compacted = newestLinesWithin(events, targetBytes);
+			const encoded = compacted + tail;
+			if (Buffer.byteLength(encoded, "utf8") > this.#maxBytes) return false;
+			temporaryPath = `${this.#path}.${process.pid}.${randomUUID()}.tmp`;
+			writeFileSync(temporaryPath, encoded, { encoding: "utf8", mode: 0o600 });
+			renameSync(temporaryPath, this.#path);
+			temporaryPath = undefined;
+			chmodSync(this.#path, 0o600);
+			return true;
+		} catch {
+			return false;
+		} finally {
+			if (temporaryPath !== undefined) {
+				try {
+					unlinkSync(temporaryPath);
+				} catch {
+					// Best-effort cleanup of an uncommitted compacted snapshot.
+				}
+			}
+			lease.release();
+		}
+	}
+}

package/src/diagnostics.ts

@@ -0,0 +1,309 @@
+const MAX_DIAGNOSTIC_LENGTH = 512;
+const REDACTED = "[REDACTED]";
+const SENSITIVE_NAME_FRAGMENT = /(?:authorization|authentication|auth|token|credential|secret|cookie|apikey)/;
+const PRIVATE_REASONING_KEY = /^(?:thinking|reasoning)/;
+const TOKEN_QUOTA_REMAINING_HEADERS = new Set([
+  "x-ratelimit-remaining-tokens",
+  "x-ratelimit-tokens-remaining",
+  "anthropic-ratelimit-tokens-remaining",
+]);
+const TOKEN_QUOTA_DURATION_RESET_HEADERS = new Set([
+  "x-ratelimit-reset-tokens",
+]);
+const TOKEN_QUOTA_ABSOLUTE_RESET_HEADERS = new Set([
+  "anthropic-ratelimit-tokens-reset",
+]);
+
+export type DiagnosticLevel = "info" | "warning" | "error";
+
+export interface DiagnosticEvent {
+  readonly timestampMs: number;
+  readonly level: DiagnosticLevel;
+  readonly category: string;
+  readonly message: string;
+  readonly fields: Readonly<Record<string, string>>;
+}
+
+/** Credential-free persistence seam; implementations must fail soft. */
+export interface DiagnosticPersistence {
+  readRecent(limit: number): readonly DiagnosticEvent[];
+  append(event: DiagnosticEvent): boolean;
+}
+
+function bound(value: string): string {
+  return value.slice(0, MAX_DIAGNOSTIC_LENGTH);
+}
+
+function safeString(value: unknown): string {
+  if (typeof value === "string") return value;
+  try {
+    return String(value);
+  } catch {
+    return "[UNAVAILABLE]";
+  }
+}
+
+function redactDiagnosticText(value: unknown): string {
+  return safeString(value)
+    .replace(
+      /\b(?:proxy[-_\s]*)?authorization\b["']?\s*[:=]\s*(?:["'][^"']*["']|(?:bearer|basic)\s+[^\s,;}&]+|[^\s,;}&]+)/gi,
+      REDACTED,
+    )
+    .replace(/\b(?:bearer|basic)\s+[^\s,;]+/gi, REDACTED)
+    .replace(
+      /\b(?:(?:x[-_\s]+)?api[-_\s]*key|access[-_\s]*token|refresh[-_\s]*token|id[-_\s]*token)\b["']?\s*[:=]\s*(?:["'][^"']*["']|[^\s,;}&]+)/gi,
+      REDACTED,
+    )
+    .replace(/\b(?:sk|rk|pk)-(?:ant-)?[A-Za-z0-9_-]{8,}\b/g, REDACTED)
+    .replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g, REDACTED)
+    .replace(/\b(?:(?:test|synthetic)[-_]?)?(?:sk|token|canary)(?:[-_:][A-Za-z0-9._-]+)+\b/gi, REDACTED)
+    .replace(/<(?:thinking|reasoning)>[\s\S]*?<\/(?:thinking|reasoning)>/gi, REDACTED)
+    .replace(
+      /\b(?:thinking|reasoning)(?:[-_\s]*(?:content|text|detail|data|signature))?\b["']?\s*[:=]\s*(?:["'][^"']*["']|[^\n,;}&]+)/gi,
+      REDACTED,
+    )
+    .replace(/\b[A-Za-z0-9_-]{80,}\b/g, REDACTED);
+}
+
+function normalizedName(value: string): string {
+  return value.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+
+function isSensitiveName(name: string): boolean {
+  const normalized = normalizedName(name);
+  return SENSITIVE_NAME_FRAGMENT.test(normalized) || PRIVATE_REASONING_KEY.test(normalized);
+}
+
+function validTokenCount(value: string): boolean {
+  if (value.length > 32 || !/^\d+$/.test(value)) return false;
+  return Number.isSafeInteger(Number(value));
+}
+
+function validDuration(value: string): boolean {
+  if (value.length > 64) return false;
+  const matches = [...value.matchAll(/(\d+(?:\.\d+)?)(ms|s|m|h)/g)];
+  if (matches.length === 0 || matches.map((match) => match[0]).join("") !== value) {
+    return false;
+  }
+  let milliseconds = 0;
+  for (const match of matches) {
+    let multiplier = 1;
+    switch (match[2]) {
+      case "h": multiplier = 3_600_000; break;
+      case "m": multiplier = 60_000; break;
+      case "s": multiplier = 1_000; break;
+    }
+    milliseconds += Number(match[1]) * multiplier;
+    if (!Number.isSafeInteger(Math.ceil(milliseconds)) || milliseconds < 0) return false;
+  }
+  return true;
+}
+
+function validAbsoluteReset(value: string): boolean {
+  if (value.length > 128) return false;
+
+  const epoch = /^(?<seconds>[1-9]\d{9})(?:\.(?<fraction>\d{1,3}))?$/.exec(value);
+  if (epoch?.groups) {
+    const epochMs = Number(epoch.groups["seconds"]) * 1_000
+      + Number((epoch.groups["fraction"] ?? "").padEnd(3, "0"));
+    if (!Number.isSafeInteger(epochMs)) return false;
+    const fraction = epochMs % 1_000;
+    const canonical = `${Math.floor(epochMs / 1_000)}${
+      fraction === 0 ? "" : `.${String(fraction).padStart(3, "0").replace(/0+$/, "")}`
+    }`;
+    return canonical === value;
+  }
+
+  const iso = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/.exec(value);
+  if (iso) {
+    const epochMs = Date.parse(value);
+    if (!Number.isFinite(epochMs) || epochMs < 0) return false;
+    const canonical = new Date(epochMs).toISOString();
+    return canonical === (value.includes(".") ? value : value.replace(/Z$/, ".000Z"));
+  }
+
+  const rfc1123 = /^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), (?:0[1-9]|[12]\d|3[01]) (?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} (?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d GMT$/.exec(value);
+  if (!rfc1123) return false;
+  const epochMs = Date.parse(value);
+  return Number.isFinite(epochMs) && epochMs >= 0 && new Date(epochMs).toUTCString() === value;
+}
+
+function validatedTokenQuotaValue(name: string, value: unknown): string | undefined {
+  const normalized = name.toLowerCase();
+  const isTokenQuotaHeader = TOKEN_QUOTA_REMAINING_HEADERS.has(normalized)
+    || TOKEN_QUOTA_DURATION_RESET_HEADERS.has(normalized)
+    || TOKEN_QUOTA_ABSOLUTE_RESET_HEADERS.has(normalized);
+  if (!isTokenQuotaHeader || typeof value !== "string") return undefined;
+
+  const trimmed = value.trim();
+  if (value !== trimmed) return undefined;
+  if (TOKEN_QUOTA_REMAINING_HEADERS.has(normalized)) {
+    return validTokenCount(trimmed) ? trimmed : undefined;
+  }
+  if (TOKEN_QUOTA_DURATION_RESET_HEADERS.has(normalized)) {
+    return validDuration(trimmed) || validAbsoluteReset(trimmed) ? trimmed : undefined;
+  }
+  return validAbsoluteReset(trimmed) ? trimmed : undefined;
+}
+
+/** Sanitizes and bounds one upstream-derived diagnostic value before storage. */
+export function sanitizeDiagnosticText(value: unknown): string {
+  return bound(redactDiagnosticText(value));
+}
+
+/** Sensitive headers are replaced wholesale except for strictly validated token-quota observations. */
+export function sanitizeHeaderValue(name: string, value: unknown): string {
+  const tokenQuotaValue = validatedTokenQuotaValue(name, value);
+  if (tokenQuotaValue !== undefined) return tokenQuotaValue;
+  return isSensitiveName(name) ? REDACTED : sanitizeDiagnosticText(value);
+}
+
+function sanitizeFields(value: unknown, depth = 0): unknown {
+  if (depth > 5) return "[TRUNCATED]";
+  // Preserve JSON's native absence semantics: `undefined` is omitted from
+  // objects and rendered as null in arrays by JSON.stringify. Returning it
+  // verbatim (rather than falling through to sanitizeDiagnosticText, which
+  // would coerce it to the literal string "undefined") keeps optional status
+  // fields like coolingUntilMs / usage absent instead of a bogus string.
+  if (value === undefined) return undefined;
+  if (value === null || typeof value === "boolean" || typeof value === "number") return value;
+  if (typeof value === "string" || typeof value === "bigint" || typeof value === "symbol") {
+    return sanitizeDiagnosticText(value);
+  }
+  if (value instanceof Error) {
+    try {
+      return sanitizeDiagnosticText(value.message);
+    } catch {
+      return "[UNAVAILABLE]";
+    }
+  }
+  if (Array.isArray(value)) return value.slice(0, 50).map((entry) => sanitizeFields(entry, depth + 1));
+  if (typeof value !== "object") return sanitizeDiagnosticText(value);
+
+  const projected: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(value).slice(0, 50)) {
+    const sanitized = isSensitiveName(key)
+      ? REDACTED
+      : sanitizeFields(entry, depth + 1);
+    // Omit undefined-valued keys entirely, matching JSON.stringify's native
+    // object semantics (an absent field, not a key mapped to "undefined").
+    if (sanitized === undefined) continue;
+    projected[sanitizeDiagnosticText(key)] = sanitized;
+  }
+  return projected;
+}
+
+/** Produces a detached, sanitized JSON value; the input object is never retained. */
+export function sanitizeForJson(value: unknown): unknown {
+  return sanitizeFields(value);
+}
+
+export function sanitizedJson(value: unknown): string {
+  return JSON.stringify(sanitizeForJson(value));
+}
+
+export class DiagnosticLog {
+  readonly #events: DiagnosticEvent[] = [];
+  readonly #maxEvents: number;
+  readonly #now: () => number;
+  readonly #persistence: DiagnosticPersistence | undefined;
+
+  constructor(options: {
+    maxEvents?: number;
+    now?: () => number;
+    persistence?: DiagnosticPersistence;
+  } = {}) {
+    this.#maxEvents = options.maxEvents ?? 100;
+    this.#now = options.now ?? Date.now;
+    this.#persistence = options.persistence;
+    if (!Number.isSafeInteger(this.#maxEvents) || this.#maxEvents < 1 || this.#maxEvents > 1_000) {
+      throw new RangeError("maxEvents must be an integer from 1 through 1000.");
+    }
+    try {
+      const persisted = this.#persistence?.readRecent(this.#maxEvents) ?? [];
+      for (const event of persisted.slice(-this.#maxEvents)) {
+        this.#events.push(Object.freeze({
+          ...event,
+          fields: Object.freeze({ ...event.fields }),
+        }));
+      }
+    } catch {
+      // Diagnostics persistence is best-effort and must never block startup.
+    }
+  }
+
+  record(
+    level: DiagnosticLevel,
+    category: string,
+    message: unknown,
+    fields: Readonly<Record<string, unknown>> = {},
+  ): DiagnosticEvent {
+    const safeFields: Record<string, string> = {};
+    for (const [key, value] of Object.entries(fields)) {
+      safeFields[sanitizeDiagnosticText(key)] = sanitizeDiagnosticText(value);
+    }
+    const event = Object.freeze({
+      timestampMs: this.#now(),
+      level,
+      category: sanitizeDiagnosticText(category),
+      message: sanitizeDiagnosticText(message),
+      fields: Object.freeze(safeFields),
+    });
+    this.#events.push(event);
+    if (this.#events.length > this.#maxEvents) this.#events.splice(0, this.#events.length - this.#maxEvents);
+    try {
+      this.#persistence?.append(event);
+    } catch {
+      // Recording remains available in memory even when persistence fails.
+    }
+    return event;
+  }
+
+  recordError(category: string, _error: unknown): DiagnosticEvent {
+    // Generic errors can originate at provider, OAuth, model-selection, fetch,
+    // request, or extension boundaries. Their messages may therefore contain
+    // endpoint bodies, credential material, request payloads, or conversation
+    // content. Persist the bounded failure fact and category only; callers that
+    // possess safe structured facts record those separately.
+    return this.record(
+      "error",
+      category,
+      "An error occurred; raw details were omitted.",
+    );
+  }
+
+  recordHeaders(category: string, headers: Readonly<Record<string, unknown>>): DiagnosticEvent {
+    const safeHeaders: Record<string, string> = {};
+    for (const [name, value] of Object.entries(headers)) {
+      safeHeaders[sanitizeDiagnosticText(name)] = sanitizeHeaderValue(name, value);
+    }
+    return this.record("info", category, "Provider response headers observed.", safeHeaders);
+  }
+
+  recent(limit = 20): readonly DiagnosticEvent[] {
+    const safeLimit = Number.isSafeInteger(limit) ? Math.max(0, Math.min(limit, 100)) : 20;
+    return this.#events.slice(-safeLimit).map((event) => ({ ...event, fields: { ...event.fields } }));
+  }
+
+  formatRecent(limit = 20): string {
+    return this.recent(limit)
+      .map((event) => `${event.level} ${event.category}: ${event.message} ${sanitizedJson(event.fields)}`)
+      .join("\n");
+  }
+
+  serialize(): string {
+    return sanitizedJson(this.#events);
+  }
+
+  sanitizeOutput(value: unknown): string {
+    // Aggregate command/status output may contain many independently bounded
+    // values. Redact it again at the final sink without truncating the aggregate.
+    return redactDiagnosticText(value);
+  }
+
+  clear(): void {
+    this.#events.length = 0;
+  }
+}
+
+export { MAX_DIAGNOSTIC_LENGTH, REDACTED };