@evo-dev/core 0.0.1-alpha → 0.0.1-alpha.10

package/src/runtime-logs/index.ts

@@ -0,0 +1,790 @@
+import { appendFile, mkdir } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative } from "node:path";
+import { resolveEvoDevPaths } from "../config/paths.ts";
+import { normalizeTimestamp, sha256Short } from "../utils/index.ts";
+
+export type EvoDevLogPhase = "started" | "completed" | "failed";
+export type EvoDevDebugLogLevel = "verbose" | "debug" | "info" | "warn" | "error";
+export type EvoDevExecutionEventTarget = "claude" | "codex" | "cli" | "team" | "unknown";
+export type EvoDevExecutionEventMetadataValue = string | number | boolean | string[];
+
+export interface CliLogEntryV1 {
+  version: 1;
+  kind: "cli";
+  timestamp: string;
+  date: string;
+  phase: EvoDevLogPhase;
+  command: string | null;
+  argv: string[];
+  cwd: string | null;
+  pid: number;
+  exitCode: number | null;
+  durationMs: number | null;
+  error: string | null;
+}
+
+export interface TraceLogEntryV1 {
+  version: 1;
+  kind: "trace";
+  timestamp: string;
+  date: string;
+  phase: EvoDevLogPhase;
+  sessionKey: string;
+  target: string;
+  runtime: {
+    surface: "cli" | "plugin";
+    argv: string[];
+    runtimeFile: string | null;
+  };
+  input: {
+    stdinBytes: number | null;
+    payload: unknown;
+  } | null;
+  event: {
+    eventId: string;
+    type: string;
+    summary: string;
+    metadata: unknown;
+    decision: unknown;
+  } | null;
+  result: {
+    enabled: boolean;
+    summary: string;
+    stateWrites: string[];
+    warnings: string[];
+    formattedResponse: string | null;
+    durationMs: number | null;
+  } | null;
+  error: string | null;
+  team: TraceLogTeamContext | null;
+}
+
+export interface EvoDevExecutionEventV1 {
+  version: 1;
+  kind: "evodev-execution-event";
+  eventId: string;
+  timestamp: string;
+  date: string;
+  target: EvoDevExecutionEventTarget;
+  eventType: string;
+  projectKey: string | null;
+  runId: string | null;
+  roleId: string | null;
+  taskId: string | null;
+  sessionKey: string;
+  summary: string;
+  metadata: Record<string, EvoDevExecutionEventMetadataValue>;
+  decision: {
+    action: "allow" | "warn";
+    reason: string;
+  } | null;
+  codeAgentTraceRefId: string | null;
+  rawPayloadStored: false;
+  rawPromptStored: false;
+  rawOutputStored: false;
+  sourceContentStored: false;
+  secretsStored: false;
+}
+
+export interface DebugLogEntryV1 {
+  version: 1;
+  kind: "debug";
+  timestamp: string;
+  date: string;
+  level: EvoDevDebugLogLevel;
+  category: string;
+  message: string;
+  data: unknown;
+  context: {
+    command: string | null;
+    argv: string[];
+    cwd: string | null;
+    pid: number;
+  };
+}
+
+export interface TraceLogTeamContext {
+  runId: string;
+  roleId: string;
+  projectKey: string;
+}
+
+export interface CliLogInput {
+  phase: EvoDevLogPhase;
+  argv: string[];
+  timestamp?: Date | string;
+  cwd?: string | null;
+  pid?: number;
+  exitCode?: number | null;
+  durationMs?: number | null;
+  error?: unknown;
+}
+
+export interface TraceLogInput {
+  phase: EvoDevLogPhase;
+  target: string;
+  runtime: TraceLogEntryV1["runtime"];
+  sessionKey?: string;
+  payload?: Record<string, unknown> | null;
+  stdinBytes?: number | null;
+  event?: TraceLogEntryV1["event"] | null;
+  result?: TraceLogEntryV1["result"] | null;
+  timestamp?: Date | string;
+  error?: unknown;
+  team?: TraceLogTeamContext | null;
+}
+
+export interface EvoDevExecutionEventInput {
+  target: string;
+  eventType: string;
+  sessionKey: string;
+  summary: string;
+  metadata?: Record<string, unknown>;
+  timestamp?: Date | string;
+  eventId?: string;
+  projectKey?: string | null;
+  runId?: string | null;
+  roleId?: string | null;
+  taskId?: string | null;
+  decision?: EvoDevExecutionEventV1["decision"];
+  codeAgentTraceRefId?: string | null;
+}
+
+export interface DebugLogInput {
+  level?: EvoDevDebugLogLevel;
+  category: string;
+  message: string;
+  data?: unknown;
+  timestamp?: Date | string;
+  argv?: string[];
+  cwd?: string | null;
+  pid?: number;
+}
+
+export interface EvoDevLogPaths {
+  logsDir: string;
+  cliDir: string;
+  cliLogPath: string;
+  debugDir: string;
+  debugLogPath: string;
+  evodevEventRootDir: string;
+  evodevEventDateDir: string;
+  evodevEventSessionDir: string | null;
+  evodevEventsPath: string | null;
+  teamsRootDir: string;
+  teamRunDir: string | null;
+  teamRunAgentsDir: string | null;
+  teamAgentLogDir: string | null;
+  teamAgentEventsPath: string | null;
+  traceRootDir: string;
+  traceDateDir: string;
+  traceSessionDir: string | null;
+  traceLogPath: string | null;
+  projectRunDir: string | null;
+  projectRunAgentsDir: string | null;
+  agentLogDir: string | null;
+  agentTraceLogPath: string | null;
+}
+
+const MAX_LOG_STRING_LENGTH = 4096;
+const MAX_EVENT_STRING_LENGTH = 512;
+const MAX_DEBUG_ARRAY_LENGTH = 50;
+const MAX_DEBUG_OBJECT_KEYS = 100;
+const MAX_DEBUG_DEPTH = 5;
+const SAFE_EXECUTION_METADATA_KEYS = new Set([
+  "phase",
+  "runtimeSurface",
+  "stdinBytes",
+  "durationMs",
+  "enabled",
+  "stateWriteCount",
+  "warningCount",
+  "commandClass",
+  "exitCode",
+  "status",
+  "redactionCount",
+  "redactionLabels",
+  "normalizedEventType",
+]);
+const SENSITIVE_EVENT_TEXT_PATTERN =
+  /https?:\/\/\S+|(^|[^a-z0-9])(secret|token|password|passwd|private|internal|api[_-]?key|apikey|credential|credentials|stdout|stderr|transcript|formattedresponse|additionalcontext)([^a-z0-9]|$)|raw[\s_-]?(payload|prompt|output|source)|source[\s_-]?dump/i;
+const SAFE_REDACTION_LABELS = new Set([
+  "raw-command",
+  "raw-command-output",
+  "raw-prompt",
+  "sensitive-command",
+  "sensitive-text",
+]);
+
+export function createCliLogEntry(input: CliLogInput): CliLogEntryV1 {
+  const timestamp = normalizeTimestamp(input.timestamp);
+  return {
+    version: 1,
+    kind: "cli",
+    timestamp,
+    date: formatLocalDateKey(timestamp),
+    phase: input.phase,
+    command: input.argv[0] ?? null,
+    argv: input.argv.map((arg) => truncateString(arg)),
+    cwd: input.cwd === undefined ? process.cwd() : input.cwd,
+    pid: input.pid ?? process.pid,
+    exitCode: input.exitCode ?? null,
+    durationMs: input.durationMs ?? null,
+    error: input.error === undefined ? null : describeError(input.error),
+  };
+}
+
+export function createDebugLogEntry(input: DebugLogInput): DebugLogEntryV1 {
+  const timestamp = normalizeTimestamp(input.timestamp);
+  const argv = input.argv ?? [];
+  return {
+    version: 1,
+    kind: "debug",
+    timestamp,
+    date: formatLocalDateKey(timestamp),
+    level: input.level ?? "debug",
+    category: truncateString(input.category),
+    message: truncateString(input.message),
+    data: input.data === undefined ? null : sanitizeDebugValue(input.data),
+    context: {
+      command: argv[0] ?? null,
+      argv: argv.map((arg) => truncateString(arg)),
+      cwd: input.cwd === undefined ? process.cwd() : input.cwd,
+      pid: input.pid ?? process.pid,
+    },
+  };
+}
+
+export function createTraceLogEntry(input: TraceLogInput): TraceLogEntryV1 {
+  const timestamp = normalizeTimestamp(input.timestamp);
+  const payload = input.payload ?? null;
+  const sessionKey = input.sessionKey ?? resolveTraceSessionKey(payload);
+  return {
+    version: 1,
+    kind: "trace",
+    timestamp,
+    date: formatLocalDateKey(timestamp),
+    phase: input.phase,
+    sessionKey,
+    target: truncateString(input.target),
+    runtime: {
+      surface: input.runtime.surface,
+      argv: input.runtime.argv.map((arg) => truncateString(arg)),
+      runtimeFile:
+        input.runtime.runtimeFile === null ? null : truncateString(input.runtime.runtimeFile),
+    },
+    input:
+      payload === null
+        ? null
+        : {
+            stdinBytes: input.stdinBytes ?? null,
+            payload,
+          },
+    event: input.event === undefined ? null : input.event,
+    result: input.result === undefined ? null : input.result,
+    error: input.error === undefined ? null : describeError(input.error),
+    team:
+      input.team === undefined || input.team === null
+        ? null
+        : {
+            runId: sanitizePathSegment(input.team.runId),
+            roleId: sanitizePathSegment(input.team.roleId),
+            projectKey: sanitizePathSegment(input.team.projectKey),
+          },
+  };
+}
+
+export function createEvoDevExecutionEvent(
+  input: EvoDevExecutionEventInput,
+): EvoDevExecutionEventV1 {
+  const timestamp = normalizeTimestamp(input.timestamp);
+  const sessionKey = sanitizePersistentIdentifier(input.sessionKey, "session");
+  const target = normalizeExecutionEventTarget(input.target);
+  const eventType = sanitizeEventText(input.eventType, "unknown");
+  const projectKey =
+    input.projectKey === undefined || input.projectKey === null
+      ? null
+      : sanitizePersistentIdentifier(input.projectKey, "project");
+  const runId =
+    input.runId === undefined || input.runId === null
+      ? null
+      : sanitizePersistentIdentifier(input.runId, "run");
+  const roleId =
+    input.roleId === undefined || input.roleId === null
+      ? null
+      : sanitizePersistentIdentifier(input.roleId, "role");
+  const taskId =
+    input.taskId === undefined || input.taskId === null
+      ? null
+      : sanitizePersistentIdentifier(input.taskId, "task");
+  const metadata = sanitizeExecutionMetadata(input.metadata ?? {});
+  const summary = sanitizeEventText(input.summary, "EvoDev execution event recorded.");
+  const decision: EvoDevExecutionEventV1["decision"] =
+    input.decision === undefined || input.decision === null
+      ? null
+      : {
+          action: input.decision.action === "warn" ? "warn" : "allow",
+          reason: sanitizeEventText(input.decision.reason, "Decision reason redacted."),
+        };
+  const codeAgentTraceRefId =
+    input.codeAgentTraceRefId === undefined || input.codeAgentTraceRefId === null
+      ? null
+      : sanitizePersistentIdentifier(input.codeAgentTraceRefId, "trace-ref");
+
+  return {
+    version: 1,
+    kind: "evodev-execution-event",
+    eventId:
+      input.eventId === undefined
+        ? createExecutionEventId({
+            timestamp,
+            target,
+            eventType,
+            sessionKey,
+            projectKey,
+            runId,
+            roleId,
+            taskId,
+            summary,
+            metadata,
+          })
+        : sanitizePersistentIdentifier(input.eventId, "event"),
+    timestamp,
+    date: formatLocalDateKey(timestamp),
+    target,
+    eventType,
+    projectKey,
+    runId,
+    roleId,
+    taskId,
+    sessionKey,
+    summary,
+    metadata,
+    decision,
+    codeAgentTraceRefId,
+    rawPayloadStored: false,
+    rawPromptStored: false,
+    rawOutputStored: false,
+    sourceContentStored: false,
+    secretsStored: false,
+  };
+}
+
+export function resolveEvoDevLogPaths(input: {
+  homeDir: string;
+  timestamp?: Date | string;
+  sessionKey?: string | null;
+  team?: TraceLogTeamContext | null;
+}): EvoDevLogPaths {
+  const paths = resolveEvoDevPaths(input.homeDir);
+  const date = formatLocalDateKey(normalizeTimestamp(input.timestamp));
+  const cliDir = join(paths.logsDir, "cli");
+  const debugDir = join(paths.logsDir, "debug");
+  const evodevEventRootDir = join(paths.logsDir, "evodev");
+  const evodevEventDateDir = join(evodevEventRootDir, date);
+  const evodevEventSessionDir =
+    input.sessionKey === undefined || input.sessionKey === null
+      ? null
+      : join(evodevEventDateDir, sanitizePersistentIdentifier(input.sessionKey, "session"));
+  const teamsRootDir = join(paths.logsDir, "teams");
+  const teamRunDir =
+    input.team === undefined || input.team === null
+      ? null
+      : join(
+          teamsRootDir,
+          sanitizePersistentIdentifier(input.team.projectKey, "project"),
+          sanitizePersistentIdentifier(input.team.runId, "run"),
+        );
+  const teamRunAgentsDir = teamRunDir === null ? null : join(teamRunDir, "agents");
+  const teamAgentLogDir =
+    teamRunAgentsDir === null || input.team === undefined || input.team === null
+      ? null
+      : join(teamRunAgentsDir, sanitizePersistentIdentifier(input.team.roleId, "role"));
+  const traceRootDir = join(paths.logsDir, "trace");
+  const traceDateDir = join(traceRootDir, date);
+  const traceSessionDir =
+    input.sessionKey === undefined || input.sessionKey === null
+      ? null
+      : join(traceDateDir, sanitizePersistentIdentifier(input.sessionKey, "session"));
+  const projectRunDir =
+    input.team === undefined || input.team === null
+      ? null
+      : join(
+          paths.logsDir,
+          sanitizePersistentIdentifier(input.team.projectKey, "project"),
+          sanitizePersistentIdentifier(input.team.runId, "run"),
+        );
+  const projectRunAgentsDir = projectRunDir === null ? null : join(projectRunDir, "agents");
+  const agentLogDir =
+    projectRunAgentsDir === null || input.team === undefined || input.team === null
+      ? null
+      : join(projectRunAgentsDir, sanitizePersistentIdentifier(input.team.roleId, "role"));
+
+  return {
+    logsDir: paths.logsDir,
+    cliDir,
+    cliLogPath: join(cliDir, `${date}.log`),
+    debugDir,
+    debugLogPath: join(debugDir, `${date}.log`),
+    evodevEventRootDir,
+    evodevEventDateDir,
+    evodevEventSessionDir,
+    evodevEventsPath:
+      evodevEventSessionDir === null ? null : join(evodevEventSessionDir, "events.jsonl"),
+    teamsRootDir,
+    teamRunDir,
+    teamRunAgentsDir,
+    teamAgentLogDir,
+    teamAgentEventsPath: teamAgentLogDir === null ? null : join(teamAgentLogDir, "events.jsonl"),
+    traceRootDir,
+    traceDateDir,
+    traceSessionDir,
+    traceLogPath: traceSessionDir === null ? null : join(traceSessionDir, "trace.log"),
+    projectRunDir,
+    projectRunAgentsDir,
+    agentLogDir,
+    agentTraceLogPath: agentLogDir === null ? null : join(agentLogDir, "trace.log"),
+  };
+}
+
+export async function appendCliLogEntry(homeDir: string, entry: CliLogEntryV1): Promise<string> {
+  const path = resolveEvoDevLogPaths({ homeDir, timestamp: entry.timestamp }).cliLogPath;
+  await appendJsonLine(path, entry);
+  return path;
+}
+
+export async function appendDebugLogEntry(
+  homeDir: string,
+  entry: DebugLogEntryV1,
+): Promise<string> {
+  const path = resolveEvoDevLogPaths({ homeDir, timestamp: entry.timestamp }).debugLogPath;
+  await appendJsonLine(path, entry);
+  return path;
+}
+
+export async function appendTraceLogEntry(
+  homeDir: string,
+  entry: TraceLogEntryV1,
+): Promise<string> {
+  const sanitizedEntry = sanitizeTraceLogEntryForAppend(entry);
+  const path = resolveEvoDevLogPaths({
+    homeDir,
+    timestamp: sanitizedEntry.timestamp,
+    sessionKey: sanitizedEntry.sessionKey,
+  }).traceLogPath;
+  if (path === null) throw new Error("Cannot resolve trace log path without a session key.");
+  await appendJsonLine(path, sanitizedEntry);
+  const agentTraceLogPath = resolveEvoDevLogPaths({
+    homeDir,
+    timestamp: sanitizedEntry.timestamp,
+    sessionKey: sanitizedEntry.sessionKey,
+    team: sanitizedEntry.team,
+  }).agentTraceLogPath;
+  if (agentTraceLogPath !== null) {
+    await appendJsonLine(agentTraceLogPath, sanitizedEntry);
+  }
+  return path;
+}
+
+export async function appendEvoDevExecutionEvent(
+  homeDir: string,
+  event: EvoDevExecutionEventV1,
+): Promise<string> {
+  const sanitizedEvent = sanitizeEvoDevExecutionEventForAppend(event);
+  const team =
+    sanitizedEvent.projectKey === null ||
+    sanitizedEvent.runId === null ||
+    sanitizedEvent.roleId === null
+      ? null
+      : {
+          projectKey: sanitizedEvent.projectKey,
+          runId: sanitizedEvent.runId,
+          roleId: sanitizedEvent.roleId,
+        };
+  const paths = resolveEvoDevLogPaths({
+    homeDir,
+    timestamp: sanitizedEvent.timestamp,
+    sessionKey: sanitizedEvent.sessionKey,
+    team,
+  });
+  if (paths.evodevEventsPath === null) {
+    throw new Error("Cannot resolve EvoDev execution event path without a session key.");
+  }
+  await appendJsonLine(paths.evodevEventsPath, sanitizedEvent);
+  if (paths.teamAgentEventsPath !== null) {
+    await appendJsonLine(paths.teamAgentEventsPath, sanitizedEvent);
+  }
+  return paths.evodevEventsPath;
+}
+
+export function resolveTraceTeamContext(input: {
+  homeDir: string;
+  environment?: Record<string, string | undefined>;
+  payload?: Record<string, unknown> | null;
+}): TraceLogTeamContext | null {
+  const environment = input.environment ?? {};
+  const runId = optionalString(environment.EVODEV_TEAM_RUN_ID);
+  const roleId = optionalString(environment.EVODEV_TEAM_ROLE_ID);
+  if (runId === null || roleId === null) return null;
+  const repoRoot =
+    optionalString(environment.EVODEV_TEAM_REPO_ROOT) ??
+    optionalString(input.payload?.cwd) ??
+    input.homeDir;
+  return {
+    runId: sanitizePersistentIdentifier(runId, "run"),
+    roleId: sanitizePersistentIdentifier(roleId, "role"),
+    projectKey: resolveProjectLogKey(input.homeDir, repoRoot),
+  };
+}
+
+export function resolveProjectLogKey(homeDir: string, repoRoot: string): string {
+  const trimmedHome = stripTrailingSlash(homeDir);
+  const trimmedRepo = stripTrailingSlash(repoRoot);
+  const relativePath = relative(trimmedHome, trimmedRepo);
+  const source =
+    relativePath !== "" && !relativePath.startsWith("..") && !isAbsolute(relativePath)
+      ? relativePath
+      : trimmedRepo.replace(/^[/\\]+/, "");
+  const projectKey =
+    source
+      .split(/[/\\]+/)
+      .filter(Boolean)
+      .map((part) => sanitizePathSegment(part))
+      .join("-") || "project-local";
+  return sanitizePersistentIdentifier(projectKey, "project");
+}
+
+export function resolveTraceSessionKey(payload: unknown): string {
+  const record = isRecord(payload) ? payload : {};
+  const sessionId = optionalString(record.session_id ?? record.sessionId);
+  const cwd = optionalString(record.cwd);
+  const source = sessionId ?? cwd ?? "local";
+  return `session-${sha256Short(source)}`;
+}
+
+function sanitizeTraceLogEntryForAppend(entry: TraceLogEntryV1): TraceLogEntryV1 {
+  return {
+    version: 1,
+    kind: "trace",
+    timestamp: normalizeTimestamp(entry.timestamp),
+    date: formatLocalDateKey(normalizeTimestamp(entry.timestamp)),
+    phase: entry.phase,
+    sessionKey: sanitizePersistentIdentifier(entry.sessionKey, "session"),
+    target: normalizeExecutionEventTarget(entry.target),
+    runtime: {
+      surface: entry.runtime.surface,
+      argv: [],
+      runtimeFile: null,
+    },
+    input:
+      entry.input === null
+        ? null
+        : {
+            stdinBytes: entry.input.stdinBytes,
+            payload: null,
+          },
+    event:
+      entry.event === null
+        ? null
+        : {
+            eventId: sanitizePersistentIdentifier(entry.event.eventId, "event"),
+            type: sanitizeEventText(entry.event.type, "unknown"),
+            summary: "Legacy trace event payload omitted; metadata-only compatibility entry.",
+            metadata: {},
+            decision: null,
+          },
+    result:
+      entry.result === null
+        ? null
+        : {
+            enabled: entry.result.enabled,
+            summary: "Legacy trace result payload omitted; metadata-only compatibility entry.",
+            stateWrites: [],
+            warnings: [],
+            formattedResponse: null,
+            durationMs: entry.result.durationMs,
+          },
+    error:
+      entry.error === null
+        ? null
+        : "Legacy trace error omitted; metadata-only compatibility entry.",
+    team:
+      entry.team === null
+        ? null
+        : {
+            runId: sanitizePersistentIdentifier(entry.team.runId, "run"),
+            roleId: sanitizePersistentIdentifier(entry.team.roleId, "role"),
+            projectKey: sanitizePersistentIdentifier(entry.team.projectKey, "project"),
+          },
+  };
+}
+
+function sanitizeEvoDevExecutionEventForAppend(
+  event: EvoDevExecutionEventV1,
+): EvoDevExecutionEventV1 {
+  return createEvoDevExecutionEvent({
+    eventId: event.eventId,
+    timestamp: event.timestamp,
+    target: event.target,
+    eventType: event.eventType,
+    projectKey: event.projectKey,
+    runId: event.runId,
+    roleId: event.roleId,
+    taskId: event.taskId,
+    sessionKey: event.sessionKey,
+    summary: event.summary,
+    metadata: event.metadata,
+    decision: event.decision,
+    codeAgentTraceRefId: event.codeAgentTraceRefId,
+  });
+}
+
+async function appendJsonLine(path: string, value: unknown): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  await appendFile(path, `${JSON.stringify(value)}\n`, "utf8");
+}
+
+function formatLocalDateKey(timestamp: string): string {
+  const date = new Date(timestamp);
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+
+function truncateString(value: string): string {
+  if (value.length <= MAX_LOG_STRING_LENGTH) return value;
+  return `${value.slice(0, MAX_LOG_STRING_LENGTH)}...[truncated:${value.length - MAX_LOG_STRING_LENGTH}]`;
+}
+
+function truncateEventString(value: string): string {
+  if (value.length <= MAX_EVENT_STRING_LENGTH) return value;
+  return `${value.slice(0, MAX_EVENT_STRING_LENGTH)}...[truncated:${value.length - MAX_EVENT_STRING_LENGTH}]`;
+}
+
+function sanitizeEventText(value: string, fallback: string): string {
+  const text = truncateEventString(value.trim());
+  if (text === "") return fallback;
+  if (SENSITIVE_EVENT_TEXT_PATTERN.test(text)) return fallback;
+  return text;
+}
+
+function sanitizeExecutionMetadata(
+  metadata: Record<string, unknown>,
+): Record<string, EvoDevExecutionEventMetadataValue> {
+  const safe: Record<string, EvoDevExecutionEventMetadataValue> = {};
+  for (const [key, value] of Object.entries(metadata)) {
+    if (!SAFE_EXECUTION_METADATA_KEYS.has(key)) continue;
+    const sanitized = sanitizeExecutionMetadataValue(key, value);
+    if (sanitized !== null) safe[key] = sanitized;
+  }
+  return safe;
+}
+
+function sanitizeExecutionMetadataValue(
+  key: string,
+  value: unknown,
+): EvoDevExecutionEventMetadataValue | null {
+  if (typeof value === "number") return Number.isFinite(value) ? value : null;
+  if (typeof value === "boolean") return value;
+  if (typeof value === "string") return sanitizeEventText(value, "[redacted]");
+  if (Array.isArray(value)) {
+    const items = value
+      .filter((item): item is string => typeof item === "string")
+      .slice(0, 50)
+      .map((item) =>
+        key === "redactionLabels" && SAFE_REDACTION_LABELS.has(item)
+          ? item
+          : sanitizeEventText(item, "[redacted]"),
+      );
+    return items;
+  }
+  return null;
+}
+
+function normalizeExecutionEventTarget(value: string): EvoDevExecutionEventTarget {
+  if (value === "claude" || value === "codex" || value === "cli" || value === "team") {
+    return value;
+  }
+  return "unknown";
+}
+
+function createExecutionEventId(input: {
+  timestamp: string;
+  target: EvoDevExecutionEventTarget;
+  eventType: string;
+  sessionKey: string;
+  projectKey: string | null;
+  runId: string | null;
+  roleId: string | null;
+  taskId: string | null;
+  summary: string;
+  metadata: Record<string, EvoDevExecutionEventMetadataValue>;
+}): string {
+  return `exec-${sha256Short(JSON.stringify(input))}`;
+}
+
+function sanitizeDebugValue(value: unknown, depth = 0): unknown {
+  if (typeof value === "string") return truncateString(value);
+  if (
+    value === null ||
+    typeof value === "number" ||
+    typeof value === "boolean" ||
+    typeof value === "undefined"
+  ) {
+    return value;
+  }
+  if (typeof value === "bigint") return value.toString();
+  if (value instanceof Error) return describeError(value);
+  if (depth >= MAX_DEBUG_DEPTH) return "[max-depth]";
+  if (Array.isArray(value)) {
+    const items = value
+      .slice(0, MAX_DEBUG_ARRAY_LENGTH)
+      .map((item) => sanitizeDebugValue(item, depth + 1));
+    if (value.length > MAX_DEBUG_ARRAY_LENGTH) {
+      items.push(`[truncated:${value.length - MAX_DEBUG_ARRAY_LENGTH}]`);
+    }
+    return items;
+  }
+  if (isRecord(value)) {
+    const output: Record<string, unknown> = {};
+    const entries = Object.entries(value).slice(0, MAX_DEBUG_OBJECT_KEYS);
+    for (const [key, nestedValue] of entries) {
+      output[truncateString(key)] = sanitizeDebugValue(nestedValue, depth + 1);
+    }
+    const extraKeys = Object.keys(value).length - entries.length;
+    if (extraKeys > 0) output["[truncatedKeys]"] = extraKeys;
+    return output;
+  }
+  return truncateString(String(value));
+}
+
+function sanitizePathSegment(value: string): string {
+  return value.replace(/[^a-zA-Z0-9._-]/g, "-").slice(0, 120) || "session-local";
+}
+
+function sanitizePersistentIdentifier(value: string, prefix: string): string {
+  const pathSafe = value.replace(/[^a-zA-Z0-9._-]/g, "-").slice(0, 120) || `${prefix}-local`;
+  if (!SENSITIVE_EVENT_TEXT_PATTERN.test(value) && !SENSITIVE_EVENT_TEXT_PATTERN.test(pathSafe)) {
+    return pathSafe;
+  }
+  return `${prefix}-${sha256Short(value)}`;
+}
+
+function stripTrailingSlash(path: string): string {
+  if (path === "/" || /^[A-Za-z]:[\\/]?$/.test(path)) return path;
+  return path.replace(/[/\\]+$/, "");
+}
+
+function optionalString(value: unknown): string | null {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+function describeError(error: unknown): string {
+  if (error instanceof Error) return truncateString(error.message);
+  return truncateString(String(error));
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}