@pellux/goodvibes-tui 0.18.4

package/src/control-plane/operator-contract-schemas-telemetry.ts

@@ -0,0 +1,349 @@
+import {
+  BOOLEAN_SCHEMA,
+  NUMBER_SCHEMA,
+  STRING_SCHEMA,
+  arraySchema,
+  objectSchema,
+} from './method-catalog-shared.ts';
+import {
+  JSON_OBJECT_SCHEMA,
+  JSON_RECORD_SCHEMA,
+  JSON_VALUE_SCHEMA,
+  STRING_LIST_SCHEMA,
+  enumSchema,
+  nullableSchema,
+  recordSchema,
+} from './operator-contract-schemas-shared.ts';
+
+const ERROR_CATEGORY_SCHEMA = enumSchema([
+  'authentication',
+  'authorization',
+  'billing',
+  'rate_limit',
+  'timeout',
+  'network',
+  'bad_request',
+  'not_found',
+  'permission',
+  'tool',
+  'config',
+  'protocol',
+  'service',
+  'internal',
+  'unknown',
+]);
+
+const ERROR_SOURCE_SCHEMA = enumSchema([
+  'provider',
+  'tool',
+  'transport',
+  'config',
+  'permission',
+  'runtime',
+  'render',
+  'acp',
+  'unknown',
+]);
+
+const AUTHENTICATED_PRINCIPAL_KIND_SCHEMA = enumSchema(['user', 'bot', 'service', 'token']);
+
+export const CONTROL_AUTH_CURRENT_MODE_SCHEMA = enumSchema(['anonymous', 'invalid', 'session', 'shared-token']);
+export const TELEMETRY_VIEW_SCHEMA = enumSchema(['safe', 'raw']);
+export const TELEMETRY_SEVERITY_SCHEMA = enumSchema(['debug', 'info', 'warn', 'error']);
+
+export const CONTROL_AUTH_CURRENT_RESPONSE_SCHEMA = objectSchema({
+  authenticated: BOOLEAN_SCHEMA,
+  authMode: CONTROL_AUTH_CURRENT_MODE_SCHEMA,
+  tokenPresent: BOOLEAN_SCHEMA,
+  authorizationHeaderPresent: BOOLEAN_SCHEMA,
+  sessionCookiePresent: BOOLEAN_SCHEMA,
+  principalId: nullableSchema(STRING_SCHEMA),
+  principalKind: nullableSchema(AUTHENTICATED_PRINCIPAL_KIND_SCHEMA),
+  admin: BOOLEAN_SCHEMA,
+  scopes: STRING_LIST_SCHEMA,
+  roles: STRING_LIST_SCHEMA,
+}, [
+  'authenticated',
+  'authMode',
+  'tokenPresent',
+  'authorizationHeaderPresent',
+  'sessionCookiePresent',
+  'principalId',
+  'principalKind',
+  'admin',
+  'scopes',
+  'roles',
+]);
+
+export const TELEMETRY_FILTER_INPUT_SCHEMA = objectSchema({
+  limit: NUMBER_SCHEMA,
+  since: NUMBER_SCHEMA,
+  until: NUMBER_SCHEMA,
+  domains: STRING_SCHEMA,
+  types: STRING_SCHEMA,
+  severity: TELEMETRY_SEVERITY_SCHEMA,
+  traceId: STRING_SCHEMA,
+  sessionId: STRING_SCHEMA,
+  turnId: STRING_SCHEMA,
+  agentId: STRING_SCHEMA,
+  taskId: STRING_SCHEMA,
+  cursor: STRING_SCHEMA,
+  view: TELEMETRY_VIEW_SCHEMA,
+});
+
+export const TELEMETRY_NORMALIZED_ERROR_SCHEMA = objectSchema({
+  name: STRING_SCHEMA,
+  message: STRING_SCHEMA,
+  summary: STRING_SCHEMA,
+  hint: STRING_SCHEMA,
+  code: STRING_SCHEMA,
+  category: ERROR_CATEGORY_SCHEMA,
+  source: ERROR_SOURCE_SCHEMA,
+  recoverable: BOOLEAN_SCHEMA,
+  statusCode: NUMBER_SCHEMA,
+  provider: STRING_SCHEMA,
+  operation: STRING_SCHEMA,
+  phase: STRING_SCHEMA,
+  requestId: STRING_SCHEMA,
+  providerCode: STRING_SCHEMA,
+  providerType: STRING_SCHEMA,
+  retryAfterMs: NUMBER_SCHEMA,
+}, ['name', 'message', 'summary', 'category', 'source', 'recoverable']);
+
+export const TELEMETRY_RECORD_SCHEMA = objectSchema({
+  id: STRING_SCHEMA,
+  domain: STRING_SCHEMA,
+  type: STRING_SCHEMA,
+  timestamp: NUMBER_SCHEMA,
+  severity: TELEMETRY_SEVERITY_SCHEMA,
+  traceId: STRING_SCHEMA,
+  sessionId: STRING_SCHEMA,
+  turnId: STRING_SCHEMA,
+  agentId: STRING_SCHEMA,
+  taskId: STRING_SCHEMA,
+  source: STRING_SCHEMA,
+  message: STRING_SCHEMA,
+  payload: JSON_VALUE_SCHEMA,
+  attributes: JSON_RECORD_SCHEMA,
+  error: TELEMETRY_NORMALIZED_ERROR_SCHEMA,
+}, [
+  'id',
+  'domain',
+  'type',
+  'timestamp',
+  'severity',
+  'traceId',
+  'sessionId',
+  'source',
+  'message',
+  'payload',
+  'attributes',
+]);
+
+export const TELEMETRY_PAGE_INFO_SCHEMA = objectSchema({
+  limit: NUMBER_SCHEMA,
+  returned: NUMBER_SCHEMA,
+  hasMore: BOOLEAN_SCHEMA,
+  cursor: STRING_SCHEMA,
+  nextCursor: STRING_SCHEMA,
+}, ['limit', 'returned', 'hasMore']);
+
+const TELEMETRY_CAPABILITIES_SCHEMA = objectSchema({
+  signals: objectSchema({
+    events: BOOLEAN_SCHEMA,
+    errors: BOOLEAN_SCHEMA,
+    metrics: BOOLEAN_SCHEMA,
+    traces: BOOLEAN_SCHEMA,
+  }, ['events', 'errors', 'metrics', 'traces']),
+  encodings: objectSchema({
+    json: BOOLEAN_SCHEMA,
+    sse: BOOLEAN_SCHEMA,
+    otlpJson: objectSchema({
+      traces: BOOLEAN_SCHEMA,
+      metrics: BOOLEAN_SCHEMA,
+      logs: BOOLEAN_SCHEMA,
+    }, ['traces', 'metrics', 'logs']),
+  }, ['json', 'sse', 'otlpJson']),
+}, ['signals', 'encodings']);
+
+const TELEMETRY_TRACE_CONTEXT_SCHEMA = objectSchema({
+  traceId: STRING_SCHEMA,
+  rootSpanId: STRING_SCHEMA,
+  exportActive: BOOLEAN_SCHEMA,
+  endpoint: STRING_SCHEMA,
+}, ['traceId', 'rootSpanId', 'exportActive']);
+
+const TELEMETRY_RUNTIME_SNAPSHOT_SCHEMA = objectSchema({
+  sessionId: STRING_SCHEMA,
+  sessionStatus: STRING_SCHEMA,
+  traceContext: TELEMETRY_TRACE_CONTEXT_SCHEMA,
+  sessionCorrelationId: STRING_SCHEMA,
+  currentTurnCorrelationId: STRING_SCHEMA,
+  dbAvailable: BOOLEAN_SCHEMA,
+  dbPath: STRING_SCHEMA,
+  tasks: objectSchema({
+    total: NUMBER_SCHEMA,
+    queued: NUMBER_SCHEMA,
+    running: NUMBER_SCHEMA,
+    blocked: NUMBER_SCHEMA,
+  }, ['total', 'queued', 'running', 'blocked']),
+  agents: objectSchema({
+    total: NUMBER_SCHEMA,
+    active: NUMBER_SCHEMA,
+  }, ['total', 'active']),
+  approvals: objectSchema({
+    pending: NUMBER_SCHEMA,
+  }, ['pending']),
+}, ['sessionId', 'sessionStatus', 'sessionCorrelationId', 'dbAvailable', 'tasks', 'agents', 'approvals']);
+
+const TELEMETRY_SESSION_METRICS_SCHEMA = objectSchema({
+  turns: NUMBER_SCHEMA,
+  toolCalls: NUMBER_SCHEMA,
+  toolErrors: NUMBER_SCHEMA,
+  agentsSpawned: NUMBER_SCHEMA,
+  inputTokens: NUMBER_SCHEMA,
+  outputTokens: NUMBER_SCHEMA,
+  cacheReadTokens: NUMBER_SCHEMA,
+  permissionPrompts: NUMBER_SCHEMA,
+  permissionDenials: NUMBER_SCHEMA,
+  errors: NUMBER_SCHEMA,
+  warnings: NUMBER_SCHEMA,
+}, [
+  'turns',
+  'toolCalls',
+  'toolErrors',
+  'agentsSpawned',
+  'inputTokens',
+  'outputTokens',
+  'cacheReadTokens',
+  'permissionPrompts',
+  'permissionDenials',
+  'errors',
+  'warnings',
+]);
+
+const TELEMETRY_AGGREGATES_SCHEMA = objectSchema({
+  totalEvents: NUMBER_SCHEMA,
+  totalErrors: NUMBER_SCHEMA,
+  totalWarnings: NUMBER_SCHEMA,
+  totalSpans: NUMBER_SCHEMA,
+  byDomain: recordSchema(NUMBER_SCHEMA),
+  byEventType: recordSchema(NUMBER_SCHEMA),
+  errorsByCategory: recordSchema(NUMBER_SCHEMA),
+}, ['totalEvents', 'totalErrors', 'totalWarnings', 'totalSpans', 'byDomain', 'byEventType', 'errorsByCategory']);
+
+const SPAN_CONTEXT_SCHEMA = objectSchema({
+  traceId: STRING_SCHEMA,
+  spanId: STRING_SCHEMA,
+  isValid: BOOLEAN_SCHEMA,
+}, ['traceId', 'spanId', 'isValid']);
+
+const SPAN_EVENT_SCHEMA = objectSchema({
+  name: STRING_SCHEMA,
+  timestamp: NUMBER_SCHEMA,
+  attributes: JSON_RECORD_SCHEMA,
+}, ['name', 'timestamp']);
+
+const SPAN_STATUS_SCHEMA = objectSchema({
+  code: NUMBER_SCHEMA,
+  message: STRING_SCHEMA,
+}, ['code']);
+
+export const TELEMETRY_READABLE_SPAN_SCHEMA = objectSchema({
+  name: STRING_SCHEMA,
+  kind: NUMBER_SCHEMA,
+  spanContext: SPAN_CONTEXT_SCHEMA,
+  parentSpanId: STRING_SCHEMA,
+  startTimeMs: NUMBER_SCHEMA,
+  endTimeMs: NUMBER_SCHEMA,
+  durationMs: NUMBER_SCHEMA,
+  attributes: JSON_RECORD_SCHEMA,
+  events: arraySchema(SPAN_EVENT_SCHEMA),
+  status: SPAN_STATUS_SCHEMA,
+  instrumentationScope: STRING_SCHEMA,
+}, [
+  'name',
+  'kind',
+  'spanContext',
+  'startTimeMs',
+  'endTimeMs',
+  'durationMs',
+  'attributes',
+  'events',
+  'status',
+  'instrumentationScope',
+]);
+
+function telemetryListResponseSchema(itemSchema: Record<string, unknown>): Record<string, unknown> {
+  return objectSchema({
+    version: NUMBER_SCHEMA,
+    view: TELEMETRY_VIEW_SCHEMA,
+    rawAccessible: BOOLEAN_SCHEMA,
+    items: arraySchema(itemSchema),
+    pageInfo: TELEMETRY_PAGE_INFO_SCHEMA,
+  }, ['version', 'view', 'rawAccessible', 'items', 'pageInfo']);
+}
+
+export const TELEMETRY_RECORD_LIST_RESPONSE_SCHEMA = telemetryListResponseSchema(TELEMETRY_RECORD_SCHEMA);
+export const TELEMETRY_SPAN_LIST_RESPONSE_SCHEMA = telemetryListResponseSchema(TELEMETRY_READABLE_SPAN_SCHEMA);
+
+export const TELEMETRY_STREAM_READY_SCHEMA = objectSchema({
+  version: NUMBER_SCHEMA,
+  capabilities: TELEMETRY_CAPABILITIES_SCHEMA,
+  view: TELEMETRY_VIEW_SCHEMA,
+  rawAccessible: BOOLEAN_SCHEMA,
+  resumedFrom: STRING_SCHEMA,
+}, ['version', 'capabilities', 'view', 'rawAccessible']);
+
+export const TELEMETRY_SNAPSHOT_SCHEMA = objectSchema({
+  version: NUMBER_SCHEMA,
+  view: TELEMETRY_VIEW_SCHEMA,
+  rawAccessible: BOOLEAN_SCHEMA,
+  generatedAt: NUMBER_SCHEMA,
+  service: objectSchema({
+    name: STRING_SCHEMA,
+    version: STRING_SCHEMA,
+  }, ['name', 'version']),
+  capabilities: TELEMETRY_CAPABILITIES_SCHEMA,
+  runtime: TELEMETRY_RUNTIME_SNAPSHOT_SCHEMA,
+  sessionMetrics: TELEMETRY_SESSION_METRICS_SCHEMA,
+  aggregates: TELEMETRY_AGGREGATES_SCHEMA,
+  recent: objectSchema({
+    events: TELEMETRY_RECORD_LIST_RESPONSE_SCHEMA,
+    errors: TELEMETRY_RECORD_LIST_RESPONSE_SCHEMA,
+    spans: TELEMETRY_SPAN_LIST_RESPONSE_SCHEMA,
+  }, ['events', 'errors', 'spans']),
+}, [
+  'version',
+  'view',
+  'rawAccessible',
+  'generatedAt',
+  'service',
+  'capabilities',
+  'runtime',
+  'sessionMetrics',
+  'aggregates',
+  'recent',
+]);
+
+export const TELEMETRY_METRICS_SNAPSHOT_SCHEMA = objectSchema({
+  version: NUMBER_SCHEMA,
+  view: TELEMETRY_VIEW_SCHEMA,
+  rawAccessible: BOOLEAN_SCHEMA,
+  generatedAt: NUMBER_SCHEMA,
+  runtime: TELEMETRY_RUNTIME_SNAPSHOT_SCHEMA,
+  sessionMetrics: TELEMETRY_SESSION_METRICS_SCHEMA,
+  aggregates: TELEMETRY_AGGREGATES_SCHEMA,
+}, ['version', 'view', 'rawAccessible', 'generatedAt', 'runtime', 'sessionMetrics', 'aggregates']);
+
+export const OTLP_TRACE_DOCUMENT_SCHEMA = objectSchema({
+  resourceSpans: arraySchema(JSON_OBJECT_SCHEMA),
+}, ['resourceSpans']);
+
+export const OTLP_LOG_DOCUMENT_SCHEMA = objectSchema({
+  resourceLogs: arraySchema(JSON_OBJECT_SCHEMA),
+}, ['resourceLogs']);
+
+export const OTLP_METRIC_DOCUMENT_SCHEMA = objectSchema({
+  resourceMetrics: arraySchema(JSON_OBJECT_SCHEMA),
+}, ['resourceMetrics']);

package/src/control-plane/operator-contract-schemas.ts

@@ -0,0 +1,6 @@
+export * from './operator-contract-schemas-control.ts';
+export * from './operator-contract-schemas-domains.ts';
+export * from './operator-contract-schemas-permissions.ts';
+export * from './operator-contract-schemas-remote.ts';
+export * from './operator-contract-schemas-runtime.ts';
+export * from './operator-contract-schemas-telemetry.ts';

package/src/control-plane/operator-contract.ts

@@ -0,0 +1,163 @@
+import type { GatewayEventDescriptor, GatewayMethodCatalog, GatewayMethodDescriptor } from './method-catalog.ts';
+import { getOperatorContract } from '@pellux/goodvibes-sdk/contracts';
+import {
+  BOOLEAN_SCHEMA,
+  METHOD_DESCRIPTOR_SCHEMA,
+  EVENT_DESCRIPTOR_SCHEMA,
+  NUMBER_SCHEMA,
+  STRING_SCHEMA,
+  arraySchema,
+  objectSchema,
+} from './method-catalog-shared.ts';
+import {
+  CONTROL_AUTH_CURRENT_RESPONSE_SCHEMA,
+  CONTROL_AUTH_LOGIN_REQUEST_SCHEMA,
+  CONTROL_AUTH_LOGIN_RESPONSE_SCHEMA,
+} from './operator-contract-schemas.ts';
+import type { OperatorContractManifest } from '@pellux/goodvibes-sdk/platform/types/foundation-contract';
+import { VERSION } from '../version.ts';
+import { OPERATOR_SESSION_COOKIE_NAME } from '@pellux/goodvibes-sdk/platform/security/http-auth';
+
+const OPERATOR_CONTRACT_VERSION = 1;
+const OPERATOR_WS_PATH = '/api/control-plane/ws';
+const OPERATOR_EVENTS_PATH = '/api/control-plane/events';
+const OPERATOR_METHODS_PATH = '/api/control-plane/methods';
+const OPERATOR_EVENTS_CATALOG_PATH = '/api/control-plane/events/catalog';
+const OPERATOR_AUTH_CURRENT_PATH = '/api/control-plane/auth';
+const OPERATOR_AUTH_CURRENT_ALIAS_PATHS = ['/api/control-plane/whoami'];
+const PEER_CONTRACT_PATH = '/api/remote/node-host/contract';
+const PEER_CONTRACT_ALIAS_PATHS = ['/api/remote/device/contract'];
+
+export type { OperatorContractManifest } from '@pellux/goodvibes-sdk/platform/types/foundation-contract';
+
+interface OperatorSchemaCoverage {
+  readonly methods: number;
+  readonly typedInputs: number;
+  readonly genericInputs: number;
+  readonly typedOutputs: number;
+  readonly genericOutputs: number;
+}
+
+interface OperatorEventCoverage {
+  readonly events: number;
+  readonly withDomains: number;
+  readonly withWireEvents: number;
+}
+
+const OPERATOR_CONTRACT_FRAME_SCHEMA = objectSchema({
+  type: STRING_SCHEMA,
+  fields: arraySchema(STRING_SCHEMA),
+}, ['type']);
+
+export const OPERATOR_CONTRACT_SCHEMA = objectSchema({
+  version: NUMBER_SCHEMA,
+  product: objectSchema({
+    id: STRING_SCHEMA,
+    surface: STRING_SCHEMA,
+    version: STRING_SCHEMA,
+  }, ['id', 'surface', 'version']),
+  auth: objectSchema({
+    modes: arraySchema(STRING_SCHEMA),
+    login: objectSchema({
+      method: STRING_SCHEMA,
+      path: STRING_SCHEMA,
+      requestSchema: CONTROL_AUTH_LOGIN_REQUEST_SCHEMA,
+      responseSchema: CONTROL_AUTH_LOGIN_RESPONSE_SCHEMA,
+    }, ['method', 'path', 'requestSchema', 'responseSchema']),
+    current: objectSchema({
+      method: STRING_SCHEMA,
+      path: STRING_SCHEMA,
+      aliasPaths: arraySchema(STRING_SCHEMA),
+      responseSchema: CONTROL_AUTH_CURRENT_RESPONSE_SCHEMA,
+    }, ['method', 'path', 'aliasPaths', 'responseSchema']),
+    sessionCookie: objectSchema({
+      name: STRING_SCHEMA,
+      httpOnly: BOOLEAN_SCHEMA,
+      sameSite: STRING_SCHEMA,
+      path: STRING_SCHEMA,
+    }, ['name', 'httpOnly', 'sameSite', 'path']),
+    bearer: objectSchema({
+      header: STRING_SCHEMA,
+      queryParameters: arraySchema(STRING_SCHEMA),
+    }, ['header', 'queryParameters']),
+  }, ['modes', 'login', 'current', 'sessionCookie', 'bearer']),
+  transports: objectSchema({
+    http: objectSchema({
+      statusPath: STRING_SCHEMA,
+      methodsPath: STRING_SCHEMA,
+      eventsCatalogPath: STRING_SCHEMA,
+    }, ['statusPath', 'methodsPath', 'eventsCatalogPath']),
+    sse: objectSchema({
+      path: STRING_SCHEMA,
+      query: objectSchema({
+        domains: STRING_SCHEMA,
+      }, ['domains']),
+    }, ['path', 'query']),
+    websocket: objectSchema({
+      path: STRING_SCHEMA,
+      clientFrames: arraySchema(OPERATOR_CONTRACT_FRAME_SCHEMA),
+      serverFrames: arraySchema(OPERATOR_CONTRACT_FRAME_SCHEMA),
+    }, ['path', 'clientFrames', 'serverFrames']),
+  }, ['http', 'sse', 'websocket']),
+  operator: objectSchema({
+    methods: arraySchema(METHOD_DESCRIPTOR_SCHEMA),
+    events: arraySchema(EVENT_DESCRIPTOR_SCHEMA),
+    schemaCoverage: objectSchema({
+      methods: NUMBER_SCHEMA,
+      typedInputs: NUMBER_SCHEMA,
+      genericInputs: NUMBER_SCHEMA,
+      typedOutputs: NUMBER_SCHEMA,
+      genericOutputs: NUMBER_SCHEMA,
+    }, ['methods', 'typedInputs', 'genericInputs', 'typedOutputs', 'genericOutputs']),
+    eventCoverage: objectSchema({
+      events: NUMBER_SCHEMA,
+      withDomains: NUMBER_SCHEMA,
+      withWireEvents: NUMBER_SCHEMA,
+    }, ['events', 'withDomains', 'withWireEvents']),
+  }, ['methods', 'events', 'schemaCoverage', 'eventCoverage']),
+  peer: objectSchema({
+    contractPath: STRING_SCHEMA,
+    aliasPaths: arraySchema(STRING_SCHEMA),
+    relationship: STRING_SCHEMA,
+  }, ['contractPath', 'aliasPaths', 'relationship']),
+}, ['version', 'product', 'auth', 'transports', 'operator', 'peer']);
+
+function isGenericObjectSchema(schema: Record<string, unknown> | undefined): boolean {
+  return Boolean(schema && schema.type === 'object' && !Object.hasOwn(schema, 'properties'));
+}
+
+function summarizeSchemaCoverage(methods: readonly GatewayMethodDescriptor[]): OperatorSchemaCoverage {
+  let genericInputs = 0;
+  let genericOutputs = 0;
+  for (const method of methods) {
+    if (isGenericObjectSchema(method.inputSchema)) genericInputs += 1;
+    if (isGenericObjectSchema(method.outputSchema)) genericOutputs += 1;
+  }
+  return {
+    methods: methods.length,
+    typedInputs: methods.length - genericInputs,
+    genericInputs,
+    typedOutputs: methods.length - genericOutputs,
+    genericOutputs,
+  };
+}
+
+function summarizeEventCoverage(events: readonly GatewayEventDescriptor[]): OperatorEventCoverage {
+  return {
+    events: events.length,
+    withDomains: events.filter((event) => (event.domains?.length ?? 0) > 0).length,
+    withWireEvents: events.filter((event) => (event.wireEvents?.length ?? 0) > 0).length,
+  };
+}
+
+export function buildOperatorContract(catalog: GatewayMethodCatalog): OperatorContractManifest {
+  void catalog;
+  const contract = getOperatorContract();
+  return {
+    ...contract,
+    product: {
+      ...contract.product,
+      version: VERSION,
+    },
+  };
+}