@kindgi/log 0.0.0-bootstrap.0 → 0.1.4-rc.5

package/package.json

@@ -1,7 +1,48 @@
 {
   "name": "@kindgi/log",
-  "version": "0.0.0-bootstrap.0",
-  "description": "Placeholder. The real @kindgi/log is published from github.com/kindgi/kindgi-sdk.",
+  "version": "0.1.4-rc.5",
+  "description": "Kindgi™ structured logging: levels per subsystem (with dotted inheritance), JSON and pretty formats, redaction of secret keys and token shapes, and W3C trace-context helpers. The runtime and @kindgi/api write the same records. Zero runtime dependencies.",
   "license": "Apache-2.0",
-  "repository": { "type": "git", "url": "git+https://github.com/kindgi/kindgi-sdk.git" }
-}
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kindgi/kindgi-sdk.git",
+    "directory": "packages/log"
+  },
+  "homepage": "https://github.com/kindgi/kindgi-sdk/tree/main/packages/log#readme",
+  "bugs": {
+    "url": "https://github.com/kindgi/kindgi-sdk/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
+}

package/src/env.ts

@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { LOG_LEVELS, type LogLevel, parseLogLevel, parseLogLevels } from './levels.js';
+import { createLogger } from './logger.js';
+import type { LogFormat, Logger } from './types.js';
+
+/**
+ * `KINDGI_LOG_FORMAT`'s value as a format: `json` or `pretty` as given;
+ * `auto` (the default) is pretty on a terminal or in development mode
+ * (`dev`: `KINDGI_DEV`, which every `kindgi dev` sets, so an older CLI that
+ * passes no format still shows pretty lines), and JSON otherwise. So the
+ * CLI and the runtime agree. `undefined` for any other
+ * value.
+ */
+export function resolveLogFormat(
+  raw: string | undefined,
+  context: { readonly isTTY: boolean; readonly dev?: boolean },
+): LogFormat | undefined {
+  const value = (raw ?? '').trim().toLowerCase();
+  if (value === '' || value === 'auto') {
+    return context.isTTY || context.dev === true ? 'pretty' : 'json';
+  }
+  if (value === 'json' || value === 'pretty') return value;
+  return undefined;
+}
+
+/** `KINDGI_LOG_LEVEL`'s level (`info` when unset), or the error that names a bad one. */
+function levelFromEnv(
+  raw: string | undefined,
+): LogLevel | { readonly kind: 'err'; readonly message: string } {
+  if (raw === undefined || raw.trim() === '') return 'info';
+  const parsed = parseLogLevel(raw);
+  if (parsed !== undefined) return parsed;
+  return {
+    kind: 'err',
+    message: `KINDGI_LOG_LEVEL must be one of ${LOG_LEVELS.join(', ')}, got "${raw}".`,
+  };
+}
+
+/** `KINDGI_LOG_LEVELS` entries no subsystem logs under (nor its dotted root). */
+function unknownSubsystems(
+  levels: Readonly<Record<string, LogLevel>>,
+  subsystems: readonly string[],
+): string[] {
+  const known = new Set(subsystems);
+  return Object.keys(levels)
+    .filter((name) => !known.has(name) && !known.has(name.split('.')[0] ?? name))
+    .map(
+      (name) =>
+        `KINDGI_LOG_LEVELS names "${name}", which no subsystem logs under; it has no effect.`,
+    );
+}
+
+export type LoggerFromEnv =
+  | {
+      readonly kind: 'ok';
+      readonly logger: Logger;
+      /** Settings that are wrong but harmless: log them at boot (an unknown subsystem, say). */
+      readonly problems: readonly string[];
+    }
+  | {
+      /** A setting that can't be honoured: refuse to start, naming it (exit code 2). */
+      readonly kind: 'err';
+      readonly message: string;
+    };
+
+/**
+ * The root logger from `KINDGI_LOG_LEVEL`, `KINDGI_LOG_LEVELS` and
+ * `KINDGI_LOG_FORMAT`. An unknown level or format, or a malformed
+ * `KINDGI_LOG_LEVELS`, is an error; a subsystem not in `subsystems` (when
+ * given) is a problem to report, not a refusal, so a typo doesn't stop a
+ * server. Default sink: stdout.
+ */
+export function loggerFromEnv(input: {
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly write?: (line: string) => void;
+  readonly isTTY?: boolean;
+  /** The subsystems the caller logs under, to flag an unknown one. */
+  readonly subsystems?: readonly string[];
+  /** Extra field keys to redact. */
+  readonly redact?: readonly string[];
+}): LoggerFromEnv {
+  const { env } = input;
+  const level = levelFromEnv(env.KINDGI_LOG_LEVEL);
+  if (typeof level === 'object') return level;
+  const levels = parseLogLevels(env.KINDGI_LOG_LEVELS ?? '');
+  if (levels.kind === 'err') {
+    return { kind: 'err', message: `KINDGI_LOG_LEVELS: ${levels.message}.` };
+  }
+  const isTTY = input.isTTY ?? false;
+  const dev = ['true', '1'].includes((env.KINDGI_DEV ?? '').trim().toLowerCase());
+  const format = resolveLogFormat(env.KINDGI_LOG_FORMAT, { isTTY, dev });
+  if (format === undefined) {
+    return {
+      kind: 'err',
+      message: `KINDGI_LOG_FORMAT must be auto, json or pretty, got "${env.KINDGI_LOG_FORMAT}".`,
+    };
+  }
+  const problems =
+    input.subsystems === undefined ? [] : unknownSubsystems(levels.levels, input.subsystems);
+  const write =
+    input.write ??
+    ((line: string) => {
+      if (typeof process !== 'undefined') process.stdout.write(`${line}\n`);
+    });
+  const logger = createLogger({
+    level,
+    levels: levels.levels,
+    format,
+    color: format === 'pretty' && isTTY && (env.NO_COLOR ?? '') === '',
+    write,
+    ...(input.redact !== undefined && { redact: input.redact }),
+  });
+  return { kind: 'ok', logger, problems };
+}

package/src/format.ts

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { LogLevel } from './levels.js';
+import type { LogRecord, SerializedError } from './types.js';
+
+/** The JSON format: one record per line, the schema `LogRecord` describes. */
+export function formatJson(record: LogRecord): string {
+  return JSON.stringify(record, (_key, value: unknown) =>
+    typeof value === 'bigint' ? value.toString() : value,
+  );
+}
+
+const LEVEL_LABEL: Readonly<Record<LogLevel, string>> = {
+  error: 'ERROR',
+  warn: 'WARN ',
+  info: 'INFO ',
+  debug: 'DEBUG',
+  trace: 'TRACE',
+};
+
+const COLOR: Readonly<Record<LogLevel, string>> = {
+  error: '\u001b[31m',
+  warn: '\u001b[33m',
+  info: '\u001b[36m',
+  debug: '\u001b[90m',
+  trace: '\u001b[90m',
+};
+const RESET = '\u001b[0m';
+const DIM = '\u001b[2m';
+
+const FIXED: ReadonlySet<string> = new Set([
+  'time',
+  'level',
+  'severity',
+  'subsystem',
+  'message',
+  'err',
+]);
+
+function pretty(value: unknown): string {
+  if (typeof value === 'string')
+    return /[\s"=]/.test(value) || value === '' ? JSON.stringify(value) : value;
+  if (typeof value === 'bigint') return value.toString();
+  if (value === undefined) return 'undefined';
+  return JSON.stringify(value);
+}
+
+function errorLines(err: SerializedError): string[] {
+  const head = `${err.name}: ${err.message}${err.code !== undefined ? ` (${err.code})` : ''}`;
+  const lines = [head];
+  if (err.stack !== undefined) {
+    const frames = err.stack.split('\n').filter((l) => /^\s*at /.test(l));
+    lines.push(...frames.map((f) => `    ${f.trim()}`));
+  }
+  if (err.cause !== undefined) {
+    lines.push(
+      typeof err.cause === 'string'
+        ? `  caused by: ${err.cause}`
+        : `  caused by: ${errorLines(err.cause).join('\n  ')}`,
+    );
+  }
+  return lines;
+}
+
+/**
+ * The pretty format, for a person at a terminal:
+ * `HH:MM:SS.mmm LEVEL [subsystem] message key=value …`, an error's
+ * frames on the lines after. Colours only when `color` is set (a
+ * terminal, and `NO_COLOR` unset). `omit`: fields the message already
+ * states (`LogOptions.inMessage`), left out of the line.
+ */
+export function formatPretty(
+  record: LogRecord,
+  options: { readonly color?: boolean; readonly omit?: readonly string[] } = {},
+): string {
+  const color = options.color === true;
+  const time = record.time.slice(11, 23);
+  const label = LEVEL_LABEL[record.level];
+  const omit = options.omit ?? [];
+  const fields = Object.entries(record)
+    .filter(([key, value]) => !FIXED.has(key) && value !== undefined && !omit.includes(key))
+    .map(([key, value]) => `${key}=${pretty(value)}`);
+  const head = [
+    color ? `${DIM}${time}${RESET}` : time,
+    color ? `${COLOR[record.level]}${label}${RESET}` : label,
+    `[${record.subsystem}]`,
+    record.message,
+    ...fields,
+  ].join(' ');
+  if (record.err === undefined) return head;
+  const [first, ...rest] = errorLines(record.err);
+  return [`${head} err=${pretty(first)}`, ...rest].join('\n');
+}

package/src/index.ts

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * `@kindgi/log` — Kindgi's structured logger: levels (per subsystem, with
+ * dotted inheritance), JSON and pretty formats, redaction, and the W3C
+ * trace-context helpers. Zero dependencies. The runtime and `@kindgi/api`
+ * (`createApp({ logger })`) write the same records.
+ */
+
+export type {
+  LogFields,
+  LogFormat,
+  LogOptions,
+  LogRecord,
+  Logger,
+  SerializedError,
+} from './types.js';
+export {
+  LOG_LEVELS,
+  type LogLevel,
+  type ParsedLogLevels,
+  SEVERITY,
+  levelEnabled,
+  levelFor,
+  parseLogLevel,
+  parseLogLevels,
+} from './levels.js';
+export { type CreateLoggerOptions, createLogger, noopLogger } from './logger.js';
+export { formatJson, formatPretty } from './format.js';
+export { REDACTED, isSecretKey, redactValue, scrubText } from './redact.js';
+export {
+  type TraceContext,
+  childSpan,
+  formatTraceparent,
+  newTraceContext,
+  parseTraceparent,
+  traceFromHeader,
+} from './trace.js';
+export { type LoggerFromEnv, loggerFromEnv, resolveLogFormat } from './env.js';

package/src/levels.ts

@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * Log levels, most severe first. A level says how much attention a line
+ * needs: `error` (an operator should look), `warn` (unexpected but
+ * handled), `info` (what happened, at the operator's grain), `debug` (the
+ * decisions behind it), `trace` (internals, briefly).
+ */
+export const LOG_LEVELS = ['error', 'warn', 'info', 'debug', 'trace'] as const;
+
+export type LogLevel = (typeof LOG_LEVELS)[number];
+
+const RANK: Readonly<Record<LogLevel, number>> = {
+  error: 50,
+  warn: 40,
+  info: 30,
+  debug: 20,
+  trace: 10,
+};
+
+/** Cloud Logging's severity names: Cloud Run and GKE show levels with no agent configuration. */
+export const SEVERITY: Readonly<Record<LogLevel, string>> = {
+  error: 'ERROR',
+  warn: 'WARNING',
+  info: 'INFO',
+  debug: 'DEBUG',
+  trace: 'DEBUG',
+};
+
+/** Whether a record at `level` is written by a logger at `threshold`. */
+export function levelEnabled(level: LogLevel, threshold: LogLevel): boolean {
+  return RANK[level] >= RANK[threshold];
+}
+
+/** A level's name, case and spaces aside; `undefined` when it isn't one. */
+export function parseLogLevel(raw: string): LogLevel | undefined {
+  const value = raw.trim().toLowerCase();
+  return (LOG_LEVELS as readonly string[]).includes(value) ? (value as LogLevel) : undefined;
+}
+
+export type ParsedLogLevels =
+  | { readonly kind: 'ok'; readonly levels: Readonly<Record<string, LogLevel>> }
+  | { readonly kind: 'err'; readonly message: string };
+
+/**
+ * Per-subsystem levels, `KINDGI_LOG_LEVELS`'s form: a comma list of
+ * `subsystem=level`, such as `kernel=debug,http=warn`. Empty is none. An
+ * entry that isn't `name=level`, or names no known level, is an error that
+ * quotes it. Whether a subsystem exists is the caller's question.
+ */
+export function parseLogLevels(raw: string): ParsedLogLevels {
+  const levels: Record<string, LogLevel> = {};
+  for (const entry of raw.split(',')) {
+    const trimmed = entry.trim();
+    if (trimmed === '') continue;
+    const eq = trimmed.indexOf('=');
+    const subsystem = eq === -1 ? '' : trimmed.slice(0, eq).trim();
+    const level = eq === -1 ? undefined : parseLogLevel(trimmed.slice(eq + 1));
+    if (subsystem === '' || level === undefined) {
+      return {
+        kind: 'err',
+        message: `"${trimmed}" isn't subsystem=level (levels: ${LOG_LEVELS.join(', ')})`,
+      };
+    }
+    levels[subsystem] = level;
+  }
+  return { kind: 'ok', levels };
+}
+
+/**
+ * The level for `subsystem`: its own entry, else its nearest dotted
+ * parent's (`kernel=debug` covers `kernel.sweeper`), else `fallback`.
+ */
+export function levelFor(
+  subsystem: string,
+  levels: Readonly<Record<string, LogLevel>>,
+  fallback: LogLevel,
+): LogLevel {
+  let name = subsystem;
+  for (;;) {
+    const own = levels[name];
+    if (own !== undefined) return own;
+    const dot = name.lastIndexOf('.');
+    if (dot === -1) return fallback;
+    name = name.slice(0, dot);
+  }
+}

package/src/logger.ts

@@ -0,0 +1,188 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { formatJson, formatPretty } from './format.js';
+import { type LogLevel, SEVERITY, levelEnabled, levelFor } from './levels.js';
+import { redactValue, scrubText } from './redact.js';
+import type {
+  LogFields,
+  LogFormat,
+  LogOptions,
+  LogRecord,
+  Logger,
+  SerializedError,
+} from './types.js';
+
+export interface CreateLoggerOptions {
+  /** Records below this level aren't written (`KINDGI_LOG_LEVEL`). Default `info`. */
+  readonly level?: LogLevel;
+  /** Per-subsystem levels; a dotted name inherits its parent's (`KINDGI_LOG_LEVELS`). */
+  readonly levels?: Readonly<Record<string, LogLevel>>;
+  /** `json` (one record per line) or `pretty` (for a terminal). Default `json`. */
+  readonly format?: LogFormat;
+  /** Colours in the pretty format (a terminal, `NO_COLOR` unset). Default off. */
+  readonly color?: boolean;
+  /** Where each line goes: one complete line, no trailing newline. */
+  readonly write: (line: string) => void;
+  /** More field keys to redact, on top of the built-in ones. */
+  readonly redact?: readonly string[];
+  /** The records' subsystem until a child names one. Default `root`. */
+  readonly subsystem?: string;
+  /** The clock (tests). */
+  readonly now?: () => Date;
+}
+
+/** Correlation fields, in the order a record carries them, after the fixed five. */
+const CORRELATION = [
+  'traceId',
+  'spanId',
+  'runTraceId',
+  'requestId',
+  'tenantId',
+  'projectId',
+  'orgId',
+  'runId',
+  'parentRunId',
+  'agentId',
+  'agentVersion',
+  'flowId',
+  'flowVersion',
+  'toolId',
+  'conversationId',
+  'approvalId',
+] as const;
+
+const FIXED: ReadonlySet<string> = new Set(['time', 'level', 'severity', 'subsystem', 'message']);
+
+function serializeError(err: unknown, withStack: boolean, depth = 0): SerializedError | string {
+  if (!(err instanceof Error)) return scrubText(String(err));
+  const code = (err as { readonly code?: unknown }).code;
+  const cause = (err as { readonly cause?: unknown }).cause;
+  return {
+    name: err.name,
+    message: scrubText(err.message),
+    ...(typeof code === 'string' || typeof code === 'number' ? { code: String(code) } : {}),
+    ...(withStack && err.stack !== undefined && { stack: scrubText(err.stack) }),
+    ...(cause !== undefined && depth < 3 && { cause: serializeError(cause, withStack, depth + 1) }),
+  };
+}
+
+/**
+ * Copy a record's own fields into `out`, after the fixed five and the
+ * correlation ones; an `Error` among them is serialized. A field named
+ * like one of the fixed five can't replace it: it comes back to be kept
+ * under `fields`.
+ */
+function copyFields(
+  out: Record<string, unknown>,
+  merged: Readonly<Record<string, unknown>>,
+  level: LogLevel,
+): Record<string, unknown> {
+  const reserved: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(merged)) {
+    if (value === undefined || key === 'subsystem' || key === 'err') continue;
+    if ((CORRELATION as readonly string[]).includes(key)) continue;
+    if (FIXED.has(key)) reserved[key] = value;
+    else out[key] = value instanceof Error ? serializeError(value, level === 'error') : value;
+  }
+  return reserved;
+}
+
+interface Shared {
+  readonly options: CreateLoggerOptions;
+  readonly threshold: LogLevel;
+  readonly levels: Readonly<Record<string, LogLevel>>;
+  readonly format: LogFormat;
+  readonly now: () => Date;
+}
+
+function build(shared: Shared, bindings: LogFields): Logger {
+  const subsystem =
+    typeof bindings.subsystem === 'string' && bindings.subsystem !== ''
+      ? bindings.subsystem
+      : (shared.options.subsystem ?? 'root');
+  const threshold = levelFor(subsystem, shared.levels, shared.threshold);
+  const extra = shared.options.redact ?? [];
+
+  function record(level: LogLevel, message: string, fields: LogFields | undefined): LogRecord {
+    const merged: Record<string, unknown> = { ...bindings, ...fields };
+    const out: Record<string, unknown> = {
+      time: shared.now().toISOString(),
+      level,
+      severity: SEVERITY[level],
+      subsystem,
+      message: scrubText(message),
+    };
+    for (const key of CORRELATION) {
+      if (merged[key] !== undefined) out[key] = redactValue(merged[key], extra);
+    }
+    const reserved = copyFields(out, merged, level);
+    const redacted = redactValue(out, extra) as Record<string, unknown>;
+    // The fixed five are the record's own, never redacted as fields.
+    for (const key of FIXED) redacted[key] = out[key];
+    if (Object.keys(reserved).length > 0) redacted.fields = redactValue(reserved, extra);
+    if (merged.err !== undefined) {
+      const withStack = level === 'error' || levelEnabled('debug', threshold);
+      redacted.err = serializeError(merged.err, withStack);
+    }
+    return redacted as LogRecord;
+  }
+
+  function write(level: LogLevel, message: string, fields?: LogFields, how?: LogOptions): void {
+    if (!levelEnabled(level, threshold)) return;
+    const rec = record(level, message, fields);
+    const line =
+      shared.format === 'pretty'
+        ? formatPretty(rec, {
+            color: shared.options.color === true,
+            ...(how?.inMessage !== undefined && { omit: how.inMessage }),
+          })
+        : formatJson(rec);
+    try {
+      shared.options.write(line);
+    } catch {
+      // A sink that fails must never fail the code that logged.
+    }
+  }
+
+  return {
+    error: (message, fields, how) => write('error', message, fields, how),
+    warn: (message, fields, how) => write('warn', message, fields, how),
+    info: (message, fields, how) => write('info', message, fields, how),
+    debug: (message, fields, how) => write('debug', message, fields, how),
+    trace: (message, fields, how) => write('trace', message, fields, how),
+    child: (more) => build(shared, { ...bindings, ...more }),
+    isLevelEnabled: (level) => levelEnabled(level, threshold),
+  };
+}
+
+/**
+ * A logger: records at or above its level (per subsystem, `levels`) are
+ * redacted and written to `write` as JSON or pretty lines. Logging never
+ * throws, and a failing sink is ignored.
+ */
+export function createLogger(options: CreateLoggerOptions): Logger {
+  return build(
+    {
+      options,
+      threshold: options.level ?? 'info',
+      levels: options.levels ?? {},
+      format: options.format ?? 'json',
+      now: options.now ?? (() => new Date()),
+    },
+    {},
+  );
+}
+
+/** A logger that writes nothing: the default where one isn't given (`createApp`). */
+const noop = (): void => undefined;
+
+export const noopLogger: Logger = {
+  error: noop,
+  warn: noop,
+  info: noop,
+  debug: noop,
+  trace: noop,
+  child: () => noopLogger,
+  isLevelEnabled: () => false,
+};

package/src/redact.ts

@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * Redaction, applied to every record before it's written, at every level.
+ *
+ *   1. **Keys.** A field whose key looks secret has its value replaced
+ *      with `[redacted]`, at any depth: its key, lowercased with `-` and
+ *      `_` removed, ends with `authorization`, `cookie`, `token`,
+ *      `password`, `passwd`, `secret`, `secrets`, `apikey`, `privatekey`,
+ *      `passphrase` or `credential(s)` (`accessToken`, `x-api-key`,
+ *      `secrets`), plus any the caller adds. `tokenCount` and
+ *      `promptTokens` are not secret, and stay.
+ *   2. **Values.** Every string (the message, fields, an error's message
+ *      and stack) is scrubbed of known shapes only, so ids are never
+ *      mangled: a Kindgi token (`kgi_bt_…`, `kgi_pt_…`) keeps its prefix
+ *      and its last four characters; `Bearer <anything>` becomes
+ *      `Bearer [redacted]`; a URL's password (`postgres://user:pass@`)
+ *      becomes `user:***@`.
+ *
+ * The first rule is the code rule's net: secret values are never fields
+ * to begin with (pass a secret's name, not its value).
+ */
+
+export const REDACTED = '[redacted]';
+
+const SECRET_KEY_ENDINGS: readonly string[] = [
+  'authorization',
+  'cookie',
+  'token',
+  'password',
+  'passwd',
+  'secret',
+  'secrets',
+  'apikey',
+  'privatekey',
+  'passphrase',
+  'credential',
+  'credentials',
+];
+
+const normalize = (key: string): string => key.toLowerCase().replace(/[-_]/g, '');
+
+/** Whether a field's key looks secret (see rule 1). */
+export function isSecretKey(key: string, extra: readonly string[] = []): boolean {
+  const k = normalize(key);
+  return [...SECRET_KEY_ENDINGS, ...extra.map(normalize)].some((end) => k.endsWith(end));
+}
+
+/** A Kindgi token: `kgi_` and a two-letter kind, then its body. */
+const KINDGI_TOKEN = /\bkgi_([a-z]{2})_([A-Za-z0-9._~+/=-]+)/g;
+const BEARER = /\b(Bearer)\s+[^\s"',;]+/gi;
+const URL_PASSWORD = /\b([a-z][a-z0-9+.-]*:\/\/[^\s:/@]+):[^\s@/]+@/gi;
+
+/** A string with known secret shapes masked (see rule 2). */
+export function scrubText(text: string): string {
+  return text
+    .replace(KINDGI_TOKEN, (_m, kind: string, body: string) => {
+      const tail = body.length >= 16 ? body.slice(-4) : '';
+      return `kgi_${kind}_…${tail}`;
+    })
+    .replace(BEARER, '$1 [redacted]')
+    .replace(URL_PASSWORD, '$1:***@');
+}
+
+const MAX_DEPTH = 8;
+
+/**
+ * A value with both rules applied, recursively: secret keys redacted,
+ * strings scrubbed. Plain objects and arrays are copied; anything deeper
+ * than a few levels, or a cycle (an object inside itself), becomes a
+ * marker. An object referenced twice side by side is copied twice.
+ */
+export function redactValue(
+  value: unknown,
+  extraKeys: readonly string[] = [],
+  depth = 0,
+  seen: WeakSet<object> = new WeakSet(),
+): unknown {
+  if (typeof value === 'string') return scrubText(value);
+  if (value === null || typeof value !== 'object') return value;
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value.toISOString();
+  if (seen.has(value)) return '[circular]';
+  if (depth >= MAX_DEPTH) return '[too deep]';
+  seen.add(value);
+  try {
+    if (Array.isArray(value)) return value.map((v) => redactValue(v, extraKeys, depth + 1, seen));
+    const out: Record<string, unknown> = {};
+    for (const [key, v] of Object.entries(value as Record<string, unknown>)) {
+      out[key] = isSecretKey(key, extraKeys)
+        ? REDACTED
+        : redactValue(v, extraKeys, depth + 1, seen);
+    }
+    return out;
+  } finally {
+    // `seen` holds the path from the root: a cycle is an object inside itself.
+    seen.delete(value);
+  }
+}