@brunobracaioli/aibrain 0.2.0-beta.1 → 0.3.0-beta.13

package/dist/assets/context-telemetry-reporter.mjs

@@ -0,0 +1,305 @@
+import { createHash, randomUUID } from 'node:crypto';
+
+export const TELEMETRY_SCHEMA_VERSION = 1;
+export const TELEMETRY_USAGE_THROTTLE_MS = 60_000;
+export const TELEMETRY_FRESHNESS_MS = 180_000;
+export const TELEMETRY_QUEUE_LIMIT = 32;
+export const TELEMETRY_TIMEOUT_MS = 10_000;
+export const TELEMETRY_FAILURE_COOLDOWN_MS = 60_000;
+
+const CLIENTS = new Set(['claude-code', 'codex-cli']);
+const SESSION_PHASES = new Set(['connected', 'usage', 'disconnected']);
+const OPERATION_PHASES = new Set([
+  'plan_prepared',
+  'selection_completed',
+  'notes_written',
+  'native_completed',
+  'recovery_attached',
+  'applied',
+  'fallback',
+  'failed',
+  'uncertain',
+]);
+const REASONS = new Set([
+  'provider_unavailable',
+  'insufficient_reduction',
+  'protected_context',
+  'stale_context',
+  'rate_limited',
+  'native_error',
+  'recovery_pending',
+  'recovery_uncertain',
+  'unsupported',
+  'unknown',
+]);
+const UNITS = new Set(['tokens', 'estimated_tokens', 'characters']);
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isUuid(value) {
+  return (
+    typeof value === 'string' &&
+    /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu.test(value)
+  );
+}
+
+function boundedVersion(value) {
+  return typeof value === 'string' &&
+    /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/u.test(value) &&
+    value.length <= 40
+    ? value
+    : null;
+}
+
+function hashSession(nativeSessionId) {
+  return createHash('sha256').update(String(nativeSessionId), 'utf8').digest('hex');
+}
+
+function measurement(value) {
+  if (
+    !isRecord(value) ||
+    !UNITS.has(value.unit) ||
+    !Number.isSafeInteger(value.used) ||
+    value.used < 0
+  )
+    return null;
+  if (
+    value.capacity !== undefined &&
+    (!Number.isSafeInteger(value.capacity) || value.capacity <= 0)
+  )
+    return null;
+  return {
+    unit: value.unit,
+    used: value.used,
+    ...(value.capacity === undefined ? {} : { capacity: value.capacity }),
+  };
+}
+
+function counts(value) {
+  if (!isRecord(value)) return undefined;
+  const result = {};
+  for (const key of ['eligible', 'protected', 'kept', 'reduced', 'dropped', 'selected']) {
+    if (value[key] === undefined) continue;
+    if (!Number.isSafeInteger(value[key]) || value[key] < 0 || value[key] > 1_000_000) return null;
+    result[key] = value[key];
+  }
+  return result;
+}
+
+function normalizeEvent(event, context) {
+  if (!isRecord(event) || typeof event.phase !== 'string') return null;
+  if (!SESSION_PHASES.has(event.phase) && !OPERATION_PHASES.has(event.phase)) return null;
+  const operation = OPERATION_PHASES.has(event.phase);
+  if (operation && !isUuid(event.operationId)) return null;
+  if (!SESSION_PHASES.has(event.phase) && !CLIENTS.has(context.client)) return null;
+  const result = {
+    schema_version: TELEMETRY_SCHEMA_VERSION,
+    event_id: randomUUID(),
+    session_key: context.sessionKey,
+    instance_id: context.instanceId,
+    sequence: context.nextSequence(),
+    observed_at: new Date(context.now()).toISOString(),
+    client: context.client,
+    client_version: context.clientVersion,
+    phase: event.phase,
+  };
+  if (operation) result.operation_id = event.operationId;
+  if (event.triggerPercent !== undefined) {
+    if (
+      typeof event.triggerPercent !== 'number' ||
+      !Number.isFinite(event.triggerPercent) ||
+      event.triggerPercent < 1 ||
+      event.triggerPercent > 95
+    )
+      return null;
+    result.trigger_percent = event.triggerPercent;
+  }
+  for (const key of ['measurement', 'before', 'after']) {
+    if (event[key] === undefined) continue;
+    const value = measurement(event[key]);
+    if (value === null) return null;
+    result[key] = value;
+  }
+  if (event.measurement !== undefined && event.phase === 'usage' && !result.measurement)
+    return null;
+  if (event.before !== undefined && event.after !== undefined) {
+    if (
+      result.before.unit !== result.after.unit ||
+      result.before.capacity !== result.after.capacity
+    )
+      return null;
+  }
+  if (event.counts !== undefined) {
+    const value = counts(event.counts);
+    if (value === null) return null;
+    result.counts = value;
+  }
+  if (event.reason !== undefined) {
+    if (!REASONS.has(event.reason)) return null;
+    result.reason = event.reason;
+  }
+  return result;
+}
+
+function withTimeout(promise, timeoutMs, setTimer, clearTimer) {
+  let timer;
+  return Promise.race([
+    Promise.resolve(promise),
+    new Promise((_, reject) => {
+      timer = setTimer(() => reject(new Error('telemetry_timeout')), timeoutMs);
+    }),
+  ]).finally(() => clearTimer(timer));
+}
+
+/**
+ * Create an opt-in reporter. `send` must use the adapter's existing authenticated
+ * MCP transport. Events are generated once and are never retried with a new id.
+ */
+export function createTelemetryReporter({
+  client,
+  clientVersion,
+  sessionId,
+  enabled = false,
+  disclosed = false,
+  send,
+  now = () => Date.now(),
+  timeoutMs = TELEMETRY_TIMEOUT_MS,
+  queueLimit = TELEMETRY_QUEUE_LIMIT,
+  setTimer = setTimeout,
+  clearTimer = clearTimeout,
+} = {}) {
+  const version = boundedVersion(clientVersion);
+  const validSession =
+    typeof sessionId === 'string' && sessionId.length > 0 && sessionId.length <= 256;
+  const active =
+    enabled === true &&
+    disclosed === true &&
+    CLIENTS.has(client) &&
+    version !== null &&
+    validSession &&
+    typeof send === 'function';
+  const sessionKey = validSession ? hashSession(sessionId) : '';
+  const instanceId = randomUUID();
+  let sequence = 0;
+  let stopped = false;
+  let busy = false;
+  let lastUsageAt = -Infinity;
+  let retryAfter = -Infinity;
+  const queue = [];
+  const drainWaiters = new Set();
+
+  function resolveDrainWaiters() {
+    if (busy || queue.length > 0) return;
+    for (const resolve of drainWaiters) resolve();
+    drainWaiters.clear();
+  }
+
+  function nextSequence() {
+    sequence += 1;
+    return sequence;
+  }
+
+  function drain() {
+    if (busy || stopped || queue.length === 0) return;
+    busy = true;
+    const event = queue.shift();
+    void withTimeout(
+      Promise.resolve().then(() => send(event)),
+      timeoutMs,
+      setTimer,
+      clearTimer,
+    )
+      .catch(() => {
+        // An unknown receipt cannot be retried under a new event id. Drop the
+        // failed event and observations queued behind it, then allow fresh
+        // observations after a bounded cooldown.
+        queue.length = 0;
+        retryAfter = now() + TELEMETRY_FAILURE_COOLDOWN_MS;
+      })
+      .finally(() => {
+        busy = false;
+        resolveDrainWaiters();
+        drain();
+      });
+  }
+
+  function emit(event, { essential = false, throttleUsage = false } = {}) {
+    const currentTime = now();
+    if (!active || stopped || currentTime < retryAfter) return false;
+    if (throttleUsage && currentTime - lastUsageAt < TELEMETRY_USAGE_THROTTLE_MS) return false;
+    const normalized = normalizeEvent(event, {
+      client,
+      clientVersion: version,
+      sessionKey,
+      instanceId,
+      now,
+      nextSequence,
+    });
+    if (!normalized) return false;
+    if (throttleUsage) lastUsageAt = currentTime;
+    if (queue.length >= queueLimit) {
+      const removable = queue.findIndex((item) => item.phase === 'usage');
+      if (removable >= 0) queue.splice(removable, 1);
+      else if (!essential) return false;
+      else queue.shift();
+    }
+    queue.push(normalized);
+    drain();
+    return true;
+  }
+
+  function stop() {
+    stopped = true;
+    queue.length = 0;
+    resolveDrainWaiters();
+  }
+
+  function flush(timeoutMs = TELEMETRY_TIMEOUT_MS) {
+    if (!busy && queue.length === 0) return Promise.resolve();
+    return new Promise((resolve) => {
+      let timer;
+      const complete = () => {
+        if (timer !== undefined) clearTimer(timer);
+        drainWaiters.delete(complete);
+        resolve();
+      };
+      timer = setTimer(() => {
+        // A flush timeout only discards stale queued work. Future lifecycle
+        // hooks remain eligible; explicit stop() is the terminal operation.
+        queue.length = 0;
+        complete();
+      }, timeoutMs);
+      drainWaiters.add(complete);
+    });
+  }
+
+  return Object.freeze({
+    active,
+    sessionKey,
+    instanceId,
+    emit,
+    connected: (fields = {}) => emit({ ...fields, phase: 'connected' }, { essential: true }),
+    usage: (fields = {}) => emit({ ...fields, phase: 'usage' }, { throttleUsage: true }),
+    disconnected: (fields = {}) => emit({ ...fields, phase: 'disconnected' }, { essential: true }),
+    planPrepared: (fields) => emit({ ...fields, phase: 'plan_prepared' }),
+    selectionCompleted: (fields) => emit({ ...fields, phase: 'selection_completed' }),
+    notesWritten: (fields) => emit({ ...fields, phase: 'notes_written' }),
+    nativeCompleted: (fields) => emit({ ...fields, phase: 'native_completed' }),
+    recoveryAttached: (fields) => emit({ ...fields, phase: 'recovery_attached' }),
+    fallback: (fields) => emit({ ...fields, phase: 'fallback' }),
+    failed: (fields) => emit({ ...fields, phase: 'failed' }),
+    uncertain: (fields) => emit({ ...fields, phase: 'uncertain' }),
+    flush,
+    stop,
+  });
+}
+
+export const telemetryInternals = {
+  boundedVersion,
+  counts,
+  hashSession,
+  measurement,
+  normalizeEvent,
+};