Skip to content

The Open Standard for Generative UI

5.5 KB
Raw Blame
import type { ObservabilityEvent } from "@openuidev/observability";
import type { WireEventBase } from "../core/wire";

/**
 * Shared producer↔sink contract for stream lifecycle events. The hook
 * (src/hooks/useStreamingObservability.ts) builds event details against this
 * module, and selectStreamEvent filters against the same constants, so the two
 * sides cannot silently drift.
 */
export const STREAM_EVENT_KIND = "react-lang:stream" as const;
export type StreamEventKind = typeof STREAM_EVENT_KIND;

export const STREAM_PHASE_STREAMING = "streaming" as const;
export const STREAM_PHASE_SETTLED = "settled" as const;
export type StreamPhase = typeof STREAM_PHASE_STREAMING | typeof STREAM_PHASE_SETTLED;

const MAX_RESPONSE_LENGTH = 16_384;

export interface StreamParserMetadata {
  incomplete: boolean;
  /** Identifiers referenced but never defined in the generated program. */
  unresolved: string[];
  /** Identifiers defined but not reachable from root. */
  orphaned: string[];
  statementCount: number;
}

/**
 * One error from a settled render, as shipped to ingest. `code`/`source` are
 * required and enum-like; the rest are optional identifiers. `message` is
 * free text and is stripped in minimal capture.
 */
export interface WireErrorEntry {
  code: string;
  source: string;
  component?: string;
  statementId?: string;
  toolName?: string;
  message?: string;
}

/** Detail payload the producer emits when a stream settles. */
export interface SettledStreamEventDetail {
  id: string;
  kind: StreamEventKind;
  phase: typeof STREAM_PHASE_SETTLED;
  updateIndex: number;
  response: string | null;
  responseLength: number;
  parser?: StreamParserMetadata;
  errors: unknown[];
  errorCount: number;
  message: string;
  /** `createLibrary()` instance id for the Renderer that produced this stream. */
  __libraryId?: string;
}

/** Wire shape for settled stream events sent to cloud ingest. */
export interface StreamWireEvent extends WireEventBase {
  kind: StreamEventKind;
  updateIndex: number;
  errorCount: number;
  parser?: StreamParserMetadata;
  response?: string;
  responseTruncated?: true;
  message?: string;
  errors?: WireErrorEntry[];
}

function isStreamParserMetadata(value: unknown): value is StreamParserMetadata {
  if (!value || typeof value !== "object") return false;
  const record = value as Record<string, unknown>;
  return (
    typeof record["incomplete"] === "boolean" &&
    Array.isArray(record["unresolved"]) &&
    Array.isArray(record["orphaned"]) &&
    typeof record["statementCount"] === "number"
  );
}

const OPTIONAL_ERROR_KEYS = ["component", "statementId", "toolName"] as const;

/**
 * Projects the producer's error list onto the wire shape. Entries without a
 * string `code` and `source` are dropped; `errorCount` on the wire is the
 * length of the result, so the count always matches the list.
 */
function projectErrors(raw: unknown, capture: "full" | "minimal"): WireErrorEntry[] {
  if (!Array.isArray(raw)) return [];
  const projected: WireErrorEntry[] = [];
  for (const entry of raw) {
    if (!entry || typeof entry !== "object") continue;
    const record = entry as Record<string, unknown>;
    const code = record["code"];
    const source = record["source"];
    if (typeof code !== "string" || typeof source !== "string") continue;
    const wire: WireErrorEntry = { code, source };
    for (const key of OPTIONAL_ERROR_KEYS) {
      const value = record[key];
      if (typeof value === "string") wire[key] = value;
    }
    if (capture === "full" && typeof record["message"] === "string") {
      wire.message = record["message"];
    }
    projected.push(wire);
  }
  return projected;
}

/**
 * Returns a wire event when `event` is a settled stream event the cloud sink
 * should keep; otherwise null. Kind filtering, validation, and capture shaping
 * all live here so the shared selector stays kind-agnostic.
 */
export function selectStreamEvent(
  event: ObservabilityEvent,
  capture: "full" | "minimal",
): StreamWireEvent | null {
  const { detail } = event;
  if (detail["kind"] !== STREAM_EVENT_KIND || detail["phase"] !== STREAM_PHASE_SETTLED) return null;

  const id = detail["id"];
  if (typeof id !== "string") return null;

  const updateIndex = detail["updateIndex"];
  if (typeof updateIndex !== "number" || typeof detail["errorCount"] !== "number") return null;

  const parser = isStreamParserMetadata(detail["parser"]) ? detail["parser"] : undefined;
  const errors = projectErrors(detail["errors"], capture);
  const errorCount = errors.length;

  if (capture === "minimal") {
    return {
      id,
      kind: STREAM_EVENT_KIND,
      level: event.level,
      timestamp: event.timestamp,
      updateIndex,
      errorCount,
      ...(parser ? { parser } : {}),
      ...(errors.length > 0 ? { errors } : {}),
    };
  }

  const response = typeof detail["response"] === "string" ? detail["response"] : undefined;
  let responseTruncated: true | undefined;
  let truncatedResponse = response;
  if (response && response.length > MAX_RESPONSE_LENGTH) {
    truncatedResponse = response.slice(0, MAX_RESPONSE_LENGTH);
    responseTruncated = true;
  }

  return {
    id,
    kind: STREAM_EVENT_KIND,
    level: event.level,
    timestamp: event.timestamp,
    updateIndex,
    errorCount,
    ...(parser ? { parser } : {}),
    ...(truncatedResponse !== undefined ? { response: truncatedResponse } : {}),
    ...(responseTruncated ? { responseTruncated } : {}),
    ...(typeof detail["message"] === "string" ? { message: detail["message"] } : {}),
    ...(errors.length > 0 ? { errors } : {}),
  };
}