Skip to content

The Open Standard for Generative UI

19.1 KB
Raw Blame
import {
  createParser,
  type ActionEvent,
  type OpenUIError,
  type Parser,
  type ValidationError,
} from "@openuidev/lang-core";
import { applyDataModelUpdate, mergeOpenUIStateIntoDataModel, toJsonObject } from "./json-pointer";
import { validateAgentToRendererMessage } from "./runtime-schema";
import { mergeComponentStatements } from "./statement-patch";
import type {
  A2UIClientOptions,
  ActionMessage,
  AgentFunctionResponseMessage,
  AgentToRendererMessage,
  CallAgentFunctionInput,
  DispatchActionInput,
  GenericErrorMessage,
  JsonObject,
  JsonValue,
  OpenUIActionOptions,
  ProcessResult,
  ProtocolValidationIssue,
  RendererDataModel,
  RendererMetadata,
  RendererToAgentMessage,
  SurfaceSnapshot,
  ValidationFailedErrorMessage,
} from "./types";

type SurfaceListener = () => void;
type MessageListener = (message: RendererToAgentMessage, metadata: RendererMetadata) => void;

interface PendingAgentFunction {
  surfaceId: string;
  resolve: (value: JsonValue) => void;
  reject: (error: Error) => void;
}

export class A2UIFunctionError extends Error {
  readonly code: string;

  constructor(code: string, message: string) {
    super(message);
    this.name = "A2UIFunctionError";
    this.code = code;
  }
}

function defaultId(): string {
  return (
    globalThis.crypto?.randomUUID?.() ?? `a2ui-${Date.now()}-${Math.random().toString(16).slice(2)}`
  );
}

function parseError(error: ValidationError): OpenUIError {
  return {
    source: "parser",
    code: error.code,
    message: error.message,
    statementId: error.statementId,
    component: error.component,
    path: error.path,
  };
}

function isCreateSurface(
  message: AgentToRendererMessage,
): message is Extract<AgentToRendererMessage, { createSurface: unknown }> {
  return "createSurface" in message;
}

function isUpdateComponents(
  message: AgentToRendererMessage,
): message is Extract<AgentToRendererMessage, { updateComponents: unknown }> {
  return "updateComponents" in message;
}

function isUpdateDataModel(
  message: AgentToRendererMessage,
): message is Extract<AgentToRendererMessage, { updateDataModel: unknown }> {
  return "updateDataModel" in message;
}

function isDeleteSurface(
  message: AgentToRendererMessage,
): message is Extract<AgentToRendererMessage, { deleteSurface: unknown }> {
  return "deleteSurface" in message;
}

function isCallRendererFunction(
  message: AgentToRendererMessage,
): message is Extract<AgentToRendererMessage, { callRendererFunction: unknown }> {
  return "callRendererFunction" in message;
}

function record(value: unknown): Record<string, unknown> | undefined {
  return value != null && typeof value === "object" && !Array.isArray(value)
    ? (value as Record<string, unknown>)
    : undefined;
}

function validationTarget(input: unknown): {
  surfaceId?: string;
  functionCallId?: string;
} {
  const message = record(input);
  if (!message) return {};
  for (const key of ["createSurface", "updateComponents", "updateDataModel", "deleteSurface"]) {
    const payload = record(message[key]);
    if (typeof payload?.surfaceId === "string") {
      return { surfaceId: payload.surfaceId };
    }
  }
  for (const key of ["callRendererFunction", "agentFunctionResponse"]) {
    const payload = record(message[key]);
    if (typeof payload?.functionCallId === "string") {
      return { functionCallId: payload.functionCallId };
    }
  }
  return {};
}

export class A2UIClient {
  readonly #parser: Parser;
  readonly #functions: A2UIClientOptions["functions"];
  readonly #onMessage?: A2UIClientOptions["onMessage"];
  readonly #rendererCapabilities?: A2UIClientOptions["rendererCapabilities"];
  readonly #now: () => Date;
  readonly #createId: () => string;
  readonly #surfaces = new Map<string, SurfaceSnapshot>();
  readonly #surfaceListeners = new Set<SurfaceListener>();
  readonly #messageListeners = new Set<MessageListener>();
  readonly #pendingAgentFunctions = new Map<string, PendingAgentFunction>();
  #revision = 0;

  constructor(options: A2UIClientOptions) {
    this.#parser = createParser(options.schema, options.rootName);
    this.#functions = options.functions;
    this.#onMessage = options.onMessage;
    this.#rendererCapabilities = options.rendererCapabilities;
    this.#now = options.now ?? (() => new Date());
    this.#createId = options.createId ?? defaultId;
  }

  subscribe(listener: SurfaceListener): () => void {
    this.#surfaceListeners.add(listener);
    return () => this.#surfaceListeners.delete(listener);
  }

  subscribeMessages(listener: MessageListener): () => void {
    this.#messageListeners.add(listener);
    return () => this.#messageListeners.delete(listener);
  }

  getSurface(surfaceId: string): SurfaceSnapshot | undefined {
    return this.#surfaces.get(surfaceId);
  }

  getSurfaces(): SurfaceSnapshot[] {
    return [...this.#surfaces.values()];
  }

  getRendererDataModel(): RendererDataModel | undefined {
    const surfaces = Object.fromEntries(
      [...this.#surfaces]
        .filter(([, surface]) => surface.sendDataModel)
        .map(([surfaceId, surface]) => [surfaceId, structuredClone(surface.dataModel)]),
    );
    if (Object.keys(surfaces).length === 0) return undefined;
    return {
      version: "v1.0",
      surfaces,
    };
  }

  getRendererMetadata(): RendererMetadata {
    const dataModel = this.getRendererDataModel();
    return {
      ...(this.#rendererCapabilities
        ? { a2uiRendererCapabilities: structuredClone(this.#rendererCapabilities) }
        : {}),
      ...(dataModel ? { a2uiRendererDataModel: dataModel } : {}),
    };
  }

  async process(input: unknown): Promise<ProcessResult> {
    const outbound: RendererToAgentMessage[] = [];
    const capture = (next: RendererToAgentMessage) => outbound.push(next);
    this.#messageListeners.add(capture);
    try {
      const validated = validateAgentToRendererMessage(input);
      if (!validated.success) return this.#invalidMessage(input, validated.issues, outbound);
      const message = validated.message;

      if (isCreateSurface(message)) return this.#createSurface(message, outbound);
      if (isUpdateComponents(message)) return this.#updateComponents(message, outbound);
      if (isUpdateDataModel(message)) return this.#updateDataModel(message, outbound);
      if (isDeleteSurface(message)) return this.#deleteSurface(message, outbound);
      if (isCallRendererFunction(message)) {
        return await this.#callRendererFunction(message, outbound);
      }
      return this.#agentFunctionResponse(message, outbound);
    } finally {
      this.#messageListeners.delete(capture);
    }
  }

  updateSurfaceFromOpenUIState(surfaceId: string, state: Record<string, unknown>): boolean {
    const surface = this.#surfaces.get(surfaceId);
    if (!surface) return false;
    const dataModel = mergeOpenUIStateIntoDataModel(surface.dataModel, state);
    if (JSON.stringify(dataModel) === JSON.stringify(surface.dataModel)) return false;
    this.#replaceSurface({
      ...surface,
      dataModel,
    });
    return true;
  }

  dispatchOpenUIAction(
    surfaceId: string,
    event: ActionEvent,
    options: OpenUIActionOptions = {},
  ): void {
    const eventSourceComponentId = (event as ActionEvent & { sourceComponentId?: unknown })
      .sourceComponentId;
    const context: JsonObject = {
      ...toJsonObject(event.params),
      ...(event.formState ? { formState: toJsonObject(event.formState) } : {}),
      ...options.context,
    };
    this.dispatchAction({
      surfaceId,
      sourceComponentId:
        options.sourceComponentId ??
        (typeof eventSourceComponentId === "string" ? eventSourceComponentId : "root"),
      name: options.name ?? event.type,
      userMessage: (options.userMessage ?? event.humanFriendlyMessage) || undefined,
      context,
      metadata: options.metadata,
    });
  }

  dispatchAction(input: DispatchActionInput): void {
    if (!this.#surfaces.has(input.surfaceId)) {
      this.#emitGenericError(
        "SURFACE_NOT_FOUND",
        `Unknown surface: ${input.surfaceId}`,
        input.surfaceId,
      );
      return;
    }

    const message: ActionMessage = {
      version: "v1.0",
      action: {
        name: input.name,
        ...(input.userMessage ? { userMessage: input.userMessage } : {}),
        surfaceId: input.surfaceId,
        sourceComponentId: input.sourceComponentId,
        timestamp: this.#now().toISOString(),
        context: input.context ?? {},
        ...(input.metadata ? { metadata: input.metadata } : {}),
      },
    };
    this.#emit(message);
  }

  callAgentFunction(input: CallAgentFunctionInput): Promise<JsonValue> {
    if (!this.#surfaces.has(input.surfaceId)) {
      const message = `Unknown surface: ${input.surfaceId}`;
      this.#emitGenericError("SURFACE_NOT_FOUND", message, input.surfaceId);
      return Promise.reject(new A2UIFunctionError("SURFACE_NOT_FOUND", message));
    }

    const functionCallId = this.#createId();
    return new Promise<JsonValue>((resolve, reject) => {
      this.#pendingAgentFunctions.set(functionCallId, {
        surfaceId: input.surfaceId,
        resolve,
        reject,
      });
      this.#emit({
        version: "v1.0",
        callAgentFunction: {
          surfaceId: input.surfaceId,
          functionCallId,
          callFunction: {
            call: input.call,
            ...(input.catalogId ? { catalogId: input.catalogId } : {}),
            ...(input.args ? { args: input.args } : {}),
          },
        },
      });
    });
  }

  dispose(): void {
    for (const pending of this.#pendingAgentFunctions.values()) {
      pending.reject(new A2UIFunctionError("CLIENT_DISPOSED", "A2UI client was disposed"));
    }
    this.#pendingAgentFunctions.clear();
    this.#surfaces.clear();
    this.#surfaceListeners.clear();
    this.#messageListeners.clear();
  }

  #createSurface(
    message: Extract<AgentToRendererMessage, { createSurface: unknown }>,
    outbound: RendererToAgentMessage[],
  ): ProcessResult {
    const input = message.createSurface;
    if (this.#surfaces.has(input.surfaceId)) {
      this.#emitGenericError(
        "SURFACE_ALREADY_EXISTS",
        `Surface already exists: ${input.surfaceId}`,
        input.surfaceId,
      );
      return { ok: false, outbound };
    }
    const supportedCatalogIds = this.#rendererCapabilities?.["v1.0"].supportedCatalogIds ?? [];
    if (
      input.catalogId &&
      supportedCatalogIds.length > 0 &&
      !supportedCatalogIds.includes(input.catalogId)
    ) {
      this.#emitGenericError(
        "UNSUPPORTED_CATALOG",
        `Renderer does not support catalog: ${input.catalogId}`,
        input.surfaceId,
      );
      return { ok: false, outbound };
    }

    let source = "";
    let parseResult: SurfaceSnapshot["parseResult"] = null;
    let errors: OpenUIError[] = [];
    if (input.components) {
      try {
        ({ source, parseResult, errors } = this.#mergeComponents("", input.components));
      } catch (error) {
        this.#emitValidationError(
          input.surfaceId,
          "/createSurface/components",
          error instanceof Error ? error.message : String(error),
        );
        return { ok: false, outbound };
      }
    }
    this.#replaceSurface({
      surfaceId: input.surfaceId,
      catalogId: input.catalogId,
      metadata: input.metadata,
      sendDataModel: input.sendDataModel ?? false,
      source,
      dataModel: structuredClone(input.dataModel ?? {}),
      parseResult,
      errors,
      revision: 0,
    });
    for (const error of errors) {
      this.#emitValidationError(
        input.surfaceId,
        "/createSurface/components",
        error.statementId ? `${error.statementId}: ${error.message}` : error.message,
      );
    }
    return { ok: errors.length === 0, outbound };
  }

  #updateComponents(
    message: Extract<AgentToRendererMessage, { updateComponents: unknown }>,
    outbound: RendererToAgentMessage[],
  ): ProcessResult {
    const input = message.updateComponents;
    const surface = this.#requireSurface(input.surfaceId);
    if (!surface) return { ok: false, outbound };
    try {
      const { source, parseResult, errors } = this.#mergeComponents(
        surface.source,
        input.components,
      );
      this.#replaceSurface({ ...surface, source, parseResult, errors });
      for (const error of errors) {
        this.#emitValidationError(
          input.surfaceId,
          "/updateComponents/components",
          error.statementId ? `${error.statementId}: ${error.message}` : error.message,
        );
      }
      return { ok: errors.length === 0, outbound };
    } catch (error) {
      this.#emitValidationError(
        input.surfaceId,
        "/updateComponents/components",
        error instanceof Error ? error.message : String(error),
      );
      return { ok: false, outbound };
    }
  }

  #updateDataModel(
    message: Extract<AgentToRendererMessage, { updateDataModel: unknown }>,
    outbound: RendererToAgentMessage[],
  ): ProcessResult {
    const input = message.updateDataModel;
    const surface = this.#requireSurface(input.surfaceId);
    if (!surface) return { ok: false, outbound };
    try {
      const dataModel = applyDataModelUpdate(surface.dataModel, input.path, input.value);
      this.#replaceSurface({ ...surface, dataModel });
      return { ok: true, outbound };
    } catch (error) {
      this.#emitValidationError(
        input.surfaceId,
        "/updateDataModel/path",
        error instanceof Error ? error.message : String(error),
      );
      return { ok: false, outbound };
    }
  }

  #deleteSurface(
    message: Extract<AgentToRendererMessage, { deleteSurface: unknown }>,
    outbound: RendererToAgentMessage[],
  ): ProcessResult {
    const surfaceId = message.deleteSurface.surfaceId;
    if (!this.#requireSurface(surfaceId)) return { ok: false, outbound };
    this.#surfaces.delete(surfaceId);
    for (const [functionCallId, pending] of this.#pendingAgentFunctions) {
      if (pending.surfaceId === surfaceId) {
        pending.reject(
          new A2UIFunctionError("SURFACE_DELETED", `Surface was deleted: ${surfaceId}`),
        );
        this.#pendingAgentFunctions.delete(functionCallId);
      }
    }
    this.#notify();
    return { ok: true, outbound };
  }

  async #callRendererFunction(
    message: Extract<AgentToRendererMessage, { callRendererFunction: unknown }>,
    outbound: RendererToAgentMessage[],
  ): Promise<ProcessResult> {
    const { functionCallId, callFunction } = message.callRendererFunction;
    const { call, catalogId, args = {} } = callFunction;
    const registration = this.#functions?.[call];
    if (!registration) {
      this.#emitGenericError(
        "INVALID_FUNCTION_CALL",
        `Renderer function is not registered: ${call}`,
        undefined,
        functionCallId,
      );
      return { ok: false, outbound };
    }
    const fn = typeof registration === "function" ? registration : registration.handler;
    if (
      typeof registration === "function" ||
      (registration.allowedCallers ?? "rendererOnly") === "rendererOnly" ||
      registration.catalogId !== catalogId
    ) {
      this.#emitGenericError(
        "INVALID_FUNCTION_CALL",
        `Renderer function is not callable from catalog ${catalogId}: ${call}`,
        undefined,
        functionCallId,
      );
      return { ok: false, outbound };
    }
    try {
      const value = await fn(args);
      this.#emit({
        version: "v1.0",
        rendererFunctionResponse: { functionCallId, value },
      });
      return { ok: true, outbound };
    } catch (error) {
      this.#emit({
        version: "v1.0",
        rendererFunctionResponse: {
          functionCallId,
          error: {
            code: "EXECUTION_FAILED",
            message: error instanceof Error ? error.message : String(error),
          },
        },
      });
      return { ok: false, outbound };
    }
  }

  #agentFunctionResponse(
    message: AgentFunctionResponseMessage,
    outbound: RendererToAgentMessage[],
  ): ProcessResult {
    const response = message.agentFunctionResponse;
    const pending = this.#pendingAgentFunctions.get(response.functionCallId);
    if (!pending) {
      return {
        ok: false,
        outbound,
        issues: [
          {
            path: "/agentFunctionResponse/functionCallId",
            message: `Unknown functionCallId: ${response.functionCallId}`,
          },
        ],
      };
    }
    this.#pendingAgentFunctions.delete(response.functionCallId);
    if ("error" in response) {
      pending.reject(new A2UIFunctionError(response.error.code, response.error.message));
      return { ok: true, outbound };
    }
    pending.resolve(response.value);
    return { ok: true, outbound };
  }

  #replaceSurface(surface: Omit<SurfaceSnapshot, "revision"> & { revision?: number }): void {
    this.#revision += 1;
    this.#surfaces.set(surface.surfaceId, { ...surface, revision: this.#revision });
    this.#notify();
  }

  #mergeComponents(
    existing: string,
    components: string[],
  ): Pick<SurfaceSnapshot, "source" | "parseResult" | "errors"> {
    const source = mergeComponentStatements(existing, components);
    const parseResult = this.#parser.parse(source);
    return {
      source,
      parseResult,
      errors: parseResult.meta.errors.map(parseError),
    };
  }

  #invalidMessage(
    input: unknown,
    issues: ProtocolValidationIssue[],
    outbound: RendererToAgentMessage[],
  ): ProcessResult {
    const target = validationTarget(input);
    const issue = issues[0] ?? { path: "/", message: "Invalid A2UI message" };
    if (target.surfaceId !== undefined) {
      this.#emitValidationError(target.surfaceId, issue.path, issue.message);
      return { ok: false, outbound, issues };
    }
    if (target.functionCallId !== undefined) {
      this.#emitGenericError(
        "INVALID_MESSAGE",
        `${issue.path}: ${issue.message}`,
        undefined,
        target.functionCallId,
      );
      return { ok: false, outbound, issues };
    }
    return { ok: false, outbound, issues };
  }

  #requireSurface(surfaceId: string): SurfaceSnapshot | undefined {
    const surface = this.#surfaces.get(surfaceId);
    if (!surface) {
      this.#emitGenericError("SURFACE_NOT_FOUND", `Unknown surface: ${surfaceId}`, surfaceId);
    }
    return surface;
  }

  #emitValidationError(surfaceId: string, path: string, message: string): void {
    const error: ValidationFailedErrorMessage = {
      version: "v1.0",
      error: { code: "VALIDATION_FAILED", surfaceId, path, message },
    };
    this.#emit(error);
  }

  #emitGenericError(
    code: string,
    message: string,
    surfaceId?: string,
    functionCallId?: string,
  ): void {
    if (surfaceId === undefined && functionCallId === undefined) return;
    const error: GenericErrorMessage =
      surfaceId !== undefined
        ? { version: "v1.0", error: { code, message, surfaceId } }
        : { version: "v1.0", error: { code, message, functionCallId: functionCallId! } };
    this.#emit(error);
  }

  #emit(message: RendererToAgentMessage): void {
    const metadata = this.getRendererMetadata();
    this.#onMessage?.(message, metadata);
    for (const listener of this.#messageListeners) listener(message, metadata);
  }

  #notify(): void {
    for (const listener of this.#surfaceListeners) listener();
  }
}

export function createA2UIClient(options: A2UIClientOptions): A2UIClient {
  return new A2UIClient(options);
}