@pellux/goodvibes-tui 0.18.11 → 0.18.13

package/src/runtime/telemetry/api-helpers.ts

@@ -1,517 +0,0 @@
-import { createHash } from 'node:crypto';
-import { VERSION } from '../../version.ts';
-import type { ErrorSource } from '@pellux/goodvibes-sdk/platform/types/errors';
-import type { NormalizedError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
-import { redactStructuredData } from '@pellux/goodvibes-sdk/platform/utils/redaction';
-import type {
-  AnyRuntimeEvent,
-  RuntimeEventDomain,
-  RuntimeEventEnvelope,
-} from '@pellux/goodvibes-sdk/platform/runtime/events/index';
-import type { RuntimeStore } from '../store/index.ts';
-import type {
-  AttributeValue,
-  ReadableSpan,
-  SpanAttributes,
-} from '@pellux/goodvibes-sdk/platform/runtime/telemetry/types';
-import type {
-  TelemetryAggregates,
-  TelemetryFilter,
-  TelemetryListResponse,
-  TelemetryPageInfo,
-  TelemetryRecord,
-  TelemetrySeverity,
-  TelemetryViewMode,
-} from '@pellux/goodvibes-sdk/platform/runtime/telemetry/api';
-
-export const SERVICE_NAME = 'goodvibes-tui';
-export const DEFAULT_EVENT_LIMIT = 500;
-export const DEFAULT_ERROR_LIMIT = 250;
-export const DEFAULT_SPAN_LIMIT = 250;
-
-const NANOSECONDS_PER_MILLISECOND = 1_000_000;
-const AGGREGATION_TEMPORALITY_CUMULATIVE = 2;
-const EMPTY_TRACE_DOCUMENT = { resourceSpans: [] };
-const EMPTY_LOG_DOCUMENT = { resourceLogs: [] };
-const EMPTY_METRIC_DOCUMENT = { resourceMetrics: [] };
-
-export const ALL_DOMAINS: readonly RuntimeEventDomain[] = [
-  'session',
-  'turn',
-  'providers',
-  'tools',
-  'tasks',
-  'agents',
-  'workflows',
-  'orchestration',
-  'communication',
-  'planner',
-  'permissions',
-  'plugins',
-  'mcp',
-  'transport',
-  'compaction',
-  'ui',
-  'ops',
-  'forensics',
-  'security',
-  'automation',
-  'routes',
-  'control-plane',
-  'deliveries',
-  'watchers',
-  'surfaces',
-  'knowledge',
-] as const;
-
-function hashHex(value: string, length: number): string {
-  return createHash('sha1').update(value).digest('hex').slice(0, length);
-}
-
-export function normalizeTraceId(traceId: string | undefined): string {
-  if (!traceId || traceId.trim().length === 0) return hashHex('missing-trace-id', 32);
-  const normalized = traceId.toLowerCase().replace(/[^0-9a-f]/g, '');
-  if (normalized.length === 32) return normalized;
-  if (normalized.length > 32) return normalized.slice(0, 32);
-  if (normalized.length > 0) return normalized.padEnd(32, '0');
-  return hashHex(traceId, 32);
-}
-
-export function buildSpanId(seed: string): string {
-  return hashHex(seed, 16);
-}
-
-export function appendBounded<T>(target: T[], value: T, limit: number): void {
-  target.push(value);
-  if (target.length > limit) {
-    target.splice(0, target.length - limit);
-  }
-}
-
-export function toAttributeValue(value: unknown): AttributeValue | undefined {
-  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
-    return value;
-  }
-  if (Array.isArray(value)) {
-    if (value.every((item) => typeof item === 'string')) return value as string[];
-    if (value.every((item) => typeof item === 'number')) return value as number[];
-    if (value.every((item) => typeof item === 'boolean')) return value as boolean[];
-    try {
-      return JSON.stringify(value);
-    } catch {
-      return undefined;
-    }
-  }
-  if (value === null || value === undefined) return undefined;
-  try {
-    return JSON.stringify(value);
-  } catch {
-    return undefined;
-  }
-}
-
-function toOtlpAnyValue(value: AttributeValue): Record<string, unknown> {
-  if (typeof value === 'string') return { stringValue: value };
-  if (typeof value === 'number') return { doubleValue: value };
-  if (typeof value === 'boolean') return { boolValue: value };
-  if (Array.isArray(value)) {
-    return {
-      arrayValue: {
-        values: value.map((item) => toOtlpAnyValue(item as AttributeValue)),
-      },
-    };
-  }
-  return { stringValue: String(value) };
-}
-
-export function toOtlpAttributes(attributes: Record<string, unknown>): Array<{ key: string; value: Record<string, unknown> }> {
-  const otlpAttributes: Array<{ key: string; value: Record<string, unknown> }> = [];
-  for (const [key, raw] of Object.entries(attributes)) {
-    const value = toAttributeValue(raw);
-    if (value === undefined) continue;
-    otlpAttributes.push({ key, value: toOtlpAnyValue(value) });
-  }
-  return otlpAttributes;
-}
-
-function buildResource(): { attributes: Array<{ key: string; value: Record<string, unknown> }> } {
-  return {
-    attributes: [
-      { key: 'service.name', value: { stringValue: SERVICE_NAME } },
-      { key: 'service.version', value: { stringValue: VERSION } },
-    ],
-  };
-}
-
-export function inferSeverity(type: string, error?: NormalizedError): TelemetrySeverity {
-  if (error) return 'error';
-  if (/(^|_)(WARNING|DEGRADED|BLOCKED|DENIED|REJECTED|QUARANTINED)(_|$)/.test(type)) return 'warn';
-  if (/(^|_)(PROGRESS|DELTA|START|STARTED|RUNNING|SYNCING|CONNECTING|INITIALIZING)(_|$)/.test(type)) return 'debug';
-  return 'info';
-}
-
-export function inferErrorSource(domain: RuntimeEventDomain): ErrorSource {
-  switch (domain) {
-    case 'providers':
-      return 'provider';
-    case 'tools':
-      return 'tool';
-    case 'transport':
-      return 'transport';
-    case 'permissions':
-    case 'security':
-      return 'permission';
-    default:
-      return 'runtime';
-  }
-}
-
-export function summarizePayload(type: string, payload: unknown): string {
-  if (typeof payload !== 'object' || payload === null) return type;
-  const record = payload as Record<string, unknown>;
-  const parts: string[] = [];
-  if (typeof record.provider === 'string') parts.push(`provider=${record.provider}`);
-  if (typeof record.model === 'string') parts.push(`model=${record.model}`);
-  if (typeof record.tool === 'string') parts.push(`tool=${record.tool}`);
-  if (typeof record.callId === 'string') parts.push(`call=${record.callId.slice(0, 12)}`);
-  if (typeof record.taskId === 'string') parts.push(`task=${record.taskId.slice(0, 12)}`);
-  if (typeof record.agentId === 'string') parts.push(`agent=${record.agentId.slice(0, 12)}`);
-  if (typeof record.message === 'string') parts.push(record.message);
-  if (typeof record.error === 'string') parts.push(record.error);
-  if (typeof record.reason === 'string') parts.push(record.reason);
-  if (typeof record.durationMs === 'number') parts.push(`${record.durationMs}ms`);
-  if (typeof record.progress === 'number') parts.push(`${record.progress}%`);
-  return parts.length > 0 ? `${type} ${parts.join(' ')}` : type;
-}
-
-export function normalizePayload(payload: unknown): Record<string, unknown> {
-  return typeof payload === 'object' && payload !== null ? { ...(payload as Record<string, unknown>) } : {};
-}
-
-export function extractProvider(payload: Record<string, unknown>): string | undefined {
-  return typeof payload.provider === 'string' ? payload.provider : undefined;
-}
-
-export function extractErrorCandidate(payload: Record<string, unknown>): string | undefined {
-  if (typeof payload.error === 'string' && payload.error.trim().length > 0) return payload.error;
-  if (typeof payload.message === 'string' && payload.message.trim().length > 0) return payload.message;
-  if (typeof payload.reason === 'string' && payload.reason.trim().length > 0) return payload.reason;
-  return undefined;
-}
-
-export function isErrorEventType(type: string): boolean {
-  return /(^|_)(ERROR|FAILED|FAIL|TERMINAL_FAILURE)(_|$)/.test(type);
-}
-
-export function buildAttributes(
-  domain: RuntimeEventDomain,
-  envelope: RuntimeEventEnvelope<AnyRuntimeEvent['type'], AnyRuntimeEvent>,
-  payload: Record<string, unknown>,
-): Record<string, unknown> {
-  return {
-    domain,
-    eventType: envelope.type,
-    source: envelope.source,
-    traceId: envelope.traceId,
-    sessionId: envelope.sessionId,
-    ...(envelope.turnId ? { turnId: envelope.turnId } : {}),
-    ...(envelope.agentId ? { agentId: envelope.agentId } : {}),
-    ...(envelope.taskId ? { taskId: envelope.taskId } : {}),
-    ...payload,
-  };
-}
-
-export function buildRecordId(
-  domain: RuntimeEventDomain,
-  envelope: RuntimeEventEnvelope<AnyRuntimeEvent['type'], AnyRuntimeEvent>,
-  seq: number,
-): string {
-  return `${domain}:${envelope.type}:${envelope.ts}:${seq}`;
-}
-
-export function extractRecordSequence(record: TelemetryRecord): number {
-  const lastColon = record.id.lastIndexOf(':');
-  if (lastColon < 0) return 0;
-  const parsed = Number.parseInt(record.id.slice(lastColon + 1), 10);
-  return Number.isFinite(parsed) ? parsed : 0;
-}
-
-export function buildSpanCursor(span: ReadableSpan): string {
-  return `${span.spanContext.traceId}:${span.spanContext.spanId}:${span.endTimeMs}`;
-}
-
-export function clampLimit(limit: number | undefined, fallback: number): number {
-  return Math.max(1, Math.min(500, Math.floor(limit ?? fallback)));
-}
-
-export function sanitizeRecord(record: TelemetryRecord, view: TelemetryViewMode): TelemetryRecord {
-  if (view === 'raw') return structuredClone(record);
-  return {
-    ...record,
-    payload: redactStructuredData(record.payload),
-    attributes: redactStructuredData(record.attributes) as Record<string, unknown>,
-  };
-}
-
-export function sanitizeSpan(span: ReadableSpan, view: TelemetryViewMode): ReadableSpan {
-  if (view === 'raw') return structuredClone(span);
-  return {
-    ...span,
-    attributes: redactStructuredData(span.attributes) as SpanAttributes,
-    events: span.events.map((event) => ({
-      ...event,
-      ...(event.attributes ? { attributes: redactStructuredData(event.attributes) as Record<string, AttributeValue> } : {}),
-    })),
-  };
-}
-
-export function buildListResponse<T>(
-  items: readonly T[],
-  view: TelemetryViewMode,
-  rawAccessible: boolean,
-  pageInfo: TelemetryPageInfo,
-): TelemetryListResponse<T> {
-  return {
-    version: 1,
-    view,
-    rawAccessible,
-    items,
-    pageInfo,
-  };
-}
-
-export function toObjectMap(map: Map<string, number>): Record<string, number> {
-  return Object.fromEntries([...map.entries()].sort(([left], [right]) => left.localeCompare(right)));
-}
-
-function toOtlpSeverityNumber(severity: TelemetrySeverity): number {
-  switch (severity) {
-    case 'debug':
-      return 5;
-    case 'warn':
-      return 13;
-    case 'error':
-      return 17;
-    case 'info':
-    default:
-      return 9;
-  }
-}
-
-export function buildOtlpTraceDocumentFromSpans(spans: readonly ReadableSpan[]): Record<string, unknown> {
-  if (spans.length === 0) return EMPTY_TRACE_DOCUMENT;
-
-  const grouped = new Map<string, ReadableSpan[]>();
-  for (const span of spans) {
-    const scope = span.instrumentationScope || SERVICE_NAME;
-    const bucket = grouped.get(scope) ?? [];
-    bucket.push(span);
-    grouped.set(scope, bucket);
-  }
-
-  return {
-    resourceSpans: [
-      {
-        resource: buildResource(),
-        scopeSpans: [...grouped.entries()].map(([scope, scopeSpans]) => ({
-          scope: { name: scope },
-          spans: scopeSpans.map((span) => ({
-            traceId: span.spanContext.traceId,
-            spanId: span.spanContext.spanId,
-            ...(span.parentSpanId ? { parentSpanId: span.parentSpanId } : {}),
-            name: span.name,
-            kind: span.kind,
-            startTimeUnixNano: String(span.startTimeMs * NANOSECONDS_PER_MILLISECOND),
-            endTimeUnixNano: String(span.endTimeMs * NANOSECONDS_PER_MILLISECOND),
-            attributes: toOtlpAttributes(span.attributes),
-            events: span.events.map((event) => ({
-              name: event.name,
-              timeUnixNano: String(event.timestamp * NANOSECONDS_PER_MILLISECOND),
-              attributes: toOtlpAttributes(event.attributes ?? {}),
-            })),
-            status: {
-              code: span.status.code,
-              ...(span.status.message ? { message: span.status.message } : {}),
-            },
-          })),
-        })),
-      },
-    ],
-  };
-}
-
-export function buildOtlpLogDocumentFromRecords(records: readonly TelemetryRecord[]): Record<string, unknown> {
-  if (records.length === 0) return EMPTY_LOG_DOCUMENT;
-
-  return {
-    resourceLogs: [
-      {
-        resource: buildResource(),
-        scopeLogs: [
-          {
-            scope: { name: `${SERVICE_NAME}/telemetry` },
-            logRecords: records.map((record) => ({
-              timeUnixNano: String(record.timestamp * NANOSECONDS_PER_MILLISECOND),
-              severityNumber: toOtlpSeverityNumber(record.severity),
-              severityText: record.severity.toUpperCase(),
-              body: { stringValue: record.message },
-              traceId: record.traceId,
-              attributes: toOtlpAttributes({
-                ...record.attributes,
-                telemetryRecordId: record.id,
-                severity: record.severity,
-                ...(record.error ? {
-                  errorCategory: record.error.category,
-                  errorSource: record.error.source,
-                  ...(record.error.code ? { errorCode: record.error.code } : {}),
-                  ...(record.error.statusCode !== undefined ? { errorStatusCode: record.error.statusCode } : {}),
-                  ...(record.error.provider ? { errorProvider: record.error.provider } : {}),
-                  ...(record.error.operation ? { errorOperation: record.error.operation } : {}),
-                  ...(record.error.phase ? { errorPhase: record.error.phase } : {}),
-                  ...(record.error.requestId ? { errorRequestId: record.error.requestId } : {}),
-                  ...(record.error.providerCode ? { errorProviderCode: record.error.providerCode } : {}),
-                } : {}),
-              }),
-            })),
-          },
-        ],
-      },
-    ],
-  };
-}
-
-export function buildOtlpMetricDocumentFromState(
-  state: ReturnType<RuntimeStore['getState']>,
-  aggregates: TelemetryAggregates,
-): Record<string, unknown> {
-  const now = Date.now();
-  const nowUnixNano = String(now * NANOSECONDS_PER_MILLISECOND);
-  const startUnixNano = String(Math.max(0, state.session.startedAt ?? now) * NANOSECONDS_PER_MILLISECOND);
-  const metrics = [
-    {
-      name: 'goodvibes.telemetry.events.total',
-      description: 'Total telemetry events captured by the GoodVibes telemetry API.',
-      unit: '1',
-      sum: {
-        aggregationTemporality: AGGREGATION_TEMPORALITY_CUMULATIVE,
-        isMonotonic: true,
-        dataPoints: [
-          {
-            startTimeUnixNano: startUnixNano,
-            timeUnixNano: nowUnixNano,
-            asInt: String(aggregates.totalEvents),
-          },
-        ],
-      },
-    },
-    {
-      name: 'goodvibes.telemetry.events.by_domain',
-      description: 'Telemetry events grouped by runtime event domain.',
-      unit: '1',
-      sum: {
-        aggregationTemporality: AGGREGATION_TEMPORALITY_CUMULATIVE,
-        isMonotonic: true,
-        dataPoints: Object.entries(aggregates.byDomain).map(([domain, count]) => ({
-          startTimeUnixNano: startUnixNano,
-          timeUnixNano: nowUnixNano,
-          asInt: String(count),
-          attributes: toOtlpAttributes({ domain }),
-        })),
-      },
-    },
-    {
-      name: 'goodvibes.telemetry.errors.total',
-      description: 'Telemetry errors grouped by normalized error category.',
-      unit: '1',
-      sum: {
-        aggregationTemporality: AGGREGATION_TEMPORALITY_CUMULATIVE,
-        isMonotonic: true,
-        dataPoints: Object.entries(aggregates.errorsByCategory).map(([category, count]) => ({
-          startTimeUnixNano: startUnixNano,
-          timeUnixNano: nowUnixNano,
-          asInt: String(count),
-          attributes: toOtlpAttributes({ category }),
-        })),
-      },
-    },
-    {
-      name: 'goodvibes.telemetry.spans.total',
-      description: 'Total synthesized spans retained by the GoodVibes telemetry API.',
-      unit: '1',
-      sum: {
-        aggregationTemporality: AGGREGATION_TEMPORALITY_CUMULATIVE,
-        isMonotonic: true,
-        dataPoints: [
-          {
-            startTimeUnixNano: startUnixNano,
-            timeUnixNano: nowUnixNano,
-            asInt: String(aggregates.totalSpans),
-          },
-        ],
-      },
-    },
-    {
-      name: 'goodvibes.runtime.tasks.active',
-      description: 'Currently active runtime tasks.',
-      unit: '1',
-      gauge: {
-        dataPoints: [
-          {
-            timeUnixNano: nowUnixNano,
-            asInt: String(state.tasks.runningIds.length),
-          },
-        ],
-      },
-    },
-    {
-      name: 'goodvibes.runtime.agents.active',
-      description: 'Currently active runtime agents.',
-      unit: '1',
-      gauge: {
-        dataPoints: [
-          {
-            timeUnixNano: nowUnixNano,
-            asInt: String(state.agents.activeAgentIds.length),
-          },
-        ],
-      },
-    },
-    {
-      name: 'goodvibes.session.tokens',
-      description: 'Session token counters tracked in the telemetry domain.',
-      unit: '1',
-      sum: {
-        aggregationTemporality: AGGREGATION_TEMPORALITY_CUMULATIVE,
-        isMonotonic: true,
-        dataPoints: [
-          {
-            startTimeUnixNano: startUnixNano,
-            timeUnixNano: nowUnixNano,
-            asInt: String(state.telemetry.sessionMetrics.inputTokens),
-            attributes: toOtlpAttributes({ direction: 'input' }),
-          },
-          {
-            startTimeUnixNano: startUnixNano,
-            timeUnixNano: nowUnixNano,
-            asInt: String(state.telemetry.sessionMetrics.outputTokens),
-            attributes: toOtlpAttributes({ direction: 'output' }),
-          },
-        ],
-      },
-    },
-  ];
-
-  return {
-    resourceMetrics: [
-      {
-        resource: buildResource(),
-        scopeMetrics: [
-          {
-            scope: { name: `${SERVICE_NAME}/telemetry` },
-            metrics,
-          },
-        ],
-      },
-    ],
-  };
-}