import { ComponentApi, ComponentContext, Catalog, A2uiClientAction, MessageProcessor, SurfaceModel, A2uiClientCapabilities, A2uiClientDataModel } from '@a2ui/web_core/v0_9'; export { A2uiClientAction, A2uiClientCapabilities, A2uiClientDataModel, A2uiMessage, Catalog, SurfaceModel } from '@a2ui/web_core/v0_9'; import * as React from 'react'; import { FC, ReactNode } from 'react'; import { z } from 'zod'; import { GraphStore } from '@prometheus-ags/entity-graph-core'; /** * Structural view of the official React catalog implementation. * * This keeps Prometheus declarations on the clean `web_core/v0_9` type path; * official `@a2ui/react@0.10.2` currently routes one public type through an * extensionless v0.8 declaration that breaks strict NodeNext consumers. * Runtime ownership remains entirely with the official implementation. */ interface PrometheusA2uiComponentImplementation extends ComponentApi { render: FC<{ context: ComponentContext; buildChild: (id: string, basePath?: string) => ReactNode; }>; } /** The only stable A2UI wire protocol supported by the 3.0 package. */ declare const PROMETHEUS_A2UI_PROTOCOL_VERSION: "v0.9.1"; /** Prometheus-owned catalog identity; it never impersonates the full official catalog. */ declare const PROMETHEUS_A2UI_CATALOG_ID = "urn:prometheus-ags:a2ui:catalog:v3"; /** Explicit default component allowlist derived from the official v0.9 catalog. */ declare const DEFAULT_PROMETHEUS_A2UI_COMPONENTS: readonly ["Text", "Image", "Icon", "Video", "AudioPlayer", "Row", "Column", "List", "Card", "Tabs", "Divider", "Modal", "Button", "TextField", "CheckBox", "ChoicePicker", "Slider", "DateTimeInput"]; /** * Default pure-function allowlist. `openUrl` is deliberately excluded because * navigation is an application-owned side effect and must be opted in. * * Official `@a2ui/web_core@0.12.0` removed the non-spec math and comparison * functions (`add`, `subtract`, `multiply`, `divide`, `equals`, `not_equals`, * `greater_than`, `less_than`, `contains`, `starts_with`, `ends_with`) from the * v0.9 basic catalog, so they are no longer allowlisted here. */ declare const DEFAULT_PROMETHEUS_A2UI_FUNCTIONS: readonly ["and", "or", "not", "required", "regex", "length", "numeric", "email", "formatString", "formatNumber", "formatCurrency", "formatDate", "pluralize"]; type PrometheusA2uiComponentName = (typeof DEFAULT_PROMETHEUS_A2UI_COMPONENTS)[number]; type PrometheusA2uiFunctionName = (typeof DEFAULT_PROMETHEUS_A2UI_FUNCTIONS)[number] | "openUrl"; interface PrometheusA2uiCatalogOptions { /** Stable catalog id advertised to agents. */ id?: string; /** Component names allowed from the official basic catalog. */ components?: readonly PrometheusA2uiComponentName[]; /** Function names allowed from the official basic catalog. */ functions?: readonly PrometheusA2uiFunctionName[]; /** * Application implementations that replace the official one of the same * `name`. Each must be built with `createPrometheusA2uiComponent`, and its * name must be listed in `components`. */ implementations?: readonly PrometheusA2uiComponentImplementation[]; } /** What a custom component's render function receives. */ interface PrometheusA2uiComponentRenderProps { /** Resolved properties; data bindings come with a `set` writer. */ props: Record; buildChild: (id: string, basePath?: string) => ReactNode; context: ComponentContext; } /** * The official implementation of a basic component, for use as the `api` of * `createPrometheusA2uiComponent`, which reuses its schema and so keeps the * property names and bindings of the pinned official version. */ declare function getPrometheusA2uiOfficialComponent(name: PrometheusA2uiComponentName): PrometheusA2uiComponentImplementation; /** * Build a component on the official renderer bundled in this package. * * This package bundles the official `@a2ui/react` so that CommonJS and ESM * builds agree. A component created with an application's own copy of * `@a2ui/react` therefore cannot share its surface context. Create custom * components here so they run on the same instance as the surface. */ declare function createPrometheusA2uiComponent(api: ComponentApi, render: FC): PrometheusA2uiComponentImplementation; /** * Create a catalog containing only explicitly allowed official implementations. * Unknown names throw during configuration rather than failing during render. */ declare function createPrometheusA2uiCatalog(options?: PrometheusA2uiCatalogOptions): Catalog; type A2uiActionDeniedCode = "invalid-action" | "unknown-action" | "invalid-context" | "unauthorized" | "approval-required" | "approval-denied" | "execution-failed"; type A2uiAuthorizationDecision = boolean | { allowed: boolean; reason?: string; }; interface A2uiApprovalRequest { action: A2uiClientAction; context: Record; rule: A2uiActionRule; } interface A2uiActionRule = Record> { /** Exact official action name. Wildcards are intentionally unsupported. */ name: string; /** Application-owned context schema evaluated after official action validation. */ contextSchema: z.ZodType; /** Destructive rules require an approval callback before execution. */ destructive?: boolean; /** Tenant/scope/resource authorization. Absence means deny. */ authorize?: (action: A2uiClientAction, context: TContext) => A2uiAuthorizationDecision | Promise; /** Store, adapter, or transport operation. */ execute: (action: A2uiClientAction, context: TContext) => unknown | Promise; } type A2uiActionDecision = { status: "executed"; action: A2uiClientAction; result: unknown; } | { status: "denied"; action: A2uiClientAction | null; code: A2uiActionDeniedCode; reason: string; cause?: unknown; }; interface A2uiActionPolicy { handle(action: unknown): Promise; } interface A2uiActionPolicyOptions { rules: readonly A2uiActionRule[]; requestApproval?: (request: A2uiApprovalRequest) => boolean | Promise; onDecision?: (decision: A2uiActionDecision) => void | Promise; } /** Build a default-deny policy for official A2UI client actions. */ declare function createA2uiActionPolicy(options: A2uiActionPolicyOptions): A2uiActionPolicy; /** Policy used when an application has not installed any action authority. */ declare function createDenyAllA2uiActionPolicy(onDecision?: A2uiActionPolicyOptions["onDecision"]): A2uiActionPolicy; /** * A2UI protocol version this build speaks on the wire. * * Surface messages are validated against this literal, so a peer announcing a * different version is rejected rather than partially parsed. */ declare const PROMETHEUS_A2UI_RC_PROTOCOL_VERSION: "v1.0"; declare const callFunctionSchema: z.ZodObject<{ version: z.ZodLiteral<"v1.0">; functionCallId: z.ZodString; wantResponse: z.ZodOptional; callFunction: z.ZodObject<{ call: z.ZodString; catalogId: z.ZodOptional; args: z.ZodOptional>; }, "passthrough", z.ZodTypeAny, z.objectOutputType<{ call: z.ZodString; catalogId: z.ZodOptional; args: z.ZodOptional>; }, z.ZodTypeAny, "passthrough">, z.objectInputType<{ call: z.ZodString; catalogId: z.ZodOptional; args: z.ZodOptional>; }, z.ZodTypeAny, "passthrough">>; }, "strict", z.ZodTypeAny, { version: "v1.0"; functionCallId: string; callFunction: { call: string; catalogId?: string | undefined; args?: Record | undefined; } & { [k: string]: unknown; }; wantResponse?: boolean | undefined; }, { version: "v1.0"; functionCallId: string; callFunction: { call: string; catalogId?: string | undefined; args?: Record | undefined; } & { [k: string]: unknown; }; wantResponse?: boolean | undefined; }>; declare const actionResponseSchema: z.ZodObject<{ version: z.ZodLiteral<"v1.0">; actionId: z.ZodString; actionResponse: z.ZodEffects; error: z.ZodOptional; }, "strict", z.ZodTypeAny, { value?: unknown; error?: unknown; }, { value?: unknown; error?: unknown; }>, { value?: unknown; error?: unknown; }, { value?: unknown; error?: unknown; }>; }, "strict", z.ZodTypeAny, { version: "v1.0"; actionId: string; actionResponse: { value?: unknown; error?: unknown; }; }, { version: "v1.0"; actionId: string; actionResponse: { value?: unknown; error?: unknown; }; }>; declare const prometheusA2uiV1MessageSchema: z.ZodUnion<[z.ZodObject<{ version: z.ZodLiteral<"v1.0">; createSurface: z.ZodObject<{ surfaceId: z.ZodString; catalogId: z.ZodOptional; sendDataModel: z.ZodOptional; components: z.ZodOptional, z.objectInputType<{ id: z.ZodString; component: z.ZodString; }, z.ZodTypeAny, "passthrough">>, "many">>; dataModel: z.ZodOptional>; }, "strict", z.ZodTypeAny, { surfaceId: string; catalogId?: string | undefined; sendDataModel?: boolean | undefined; components?: z.objectOutputType<{ id: z.ZodString; component: z.ZodString; }, z.ZodTypeAny, "passthrough">[] | undefined; dataModel?: Record | undefined; }, { surfaceId: string; catalogId?: string | undefined; sendDataModel?: boolean | undefined; components?: z.objectInputType<{ id: z.ZodString; component: z.ZodString; }, z.ZodTypeAny, "passthrough">[] | undefined; dataModel?: Record | undefined; }>; }, "strict", z.ZodTypeAny, { version: "v1.0"; createSurface: { surfaceId: string; catalogId?: string | undefined; sendDataModel?: boolean | undefined; components?: z.objectOutputType<{ id: z.ZodString; component: z.ZodString; }, z.ZodTypeAny, "passthrough">[] | undefined; dataModel?: Record | undefined; }; }, { version: "v1.0"; createSurface: { surfaceId: string; catalogId?: string | undefined; sendDataModel?: boolean | undefined; components?: z.objectInputType<{ id: z.ZodString; component: z.ZodString; }, z.ZodTypeAny, "passthrough">[] | undefined; dataModel?: Record | undefined; }; }>, z.ZodObject<{ version: z.ZodLiteral<"v1.0">; updateComponents: z.ZodObject<{ surfaceId: z.ZodString; components: z.ZodArray, z.objectInputType<{ id: z.ZodString; component: z.ZodString; }, z.ZodTypeAny, "passthrough">>, "many">; }, "strict", z.ZodTypeAny, { surfaceId: string; components: z.objectOutputType<{ id: z.ZodString; component: z.ZodString; }, z.ZodTypeAny, "passthrough">[]; }, { surfaceId: string; components: z.objectInputType<{ id: z.ZodString; component: z.ZodString; }, z.ZodTypeAny, "passthrough">[]; }>; }, "strict", z.ZodTypeAny, { version: "v1.0"; updateComponents: { surfaceId: string; components: z.objectOutputType<{ id: z.ZodString; component: z.ZodString; }, z.ZodTypeAny, "passthrough">[]; }; }, { version: "v1.0"; updateComponents: { surfaceId: string; components: z.objectInputType<{ id: z.ZodString; component: z.ZodString; }, z.ZodTypeAny, "passthrough">[]; }; }>, z.ZodObject<{ version: z.ZodLiteral<"v1.0">; updateDataModel: z.ZodObject<{ surfaceId: z.ZodString; path: z.ZodOptional; value: z.ZodUnknown; }, "strict", z.ZodTypeAny, { surfaceId: string; value?: unknown; path?: string | undefined; }, { surfaceId: string; value?: unknown; path?: string | undefined; }>; }, "strict", z.ZodTypeAny, { version: "v1.0"; updateDataModel: { surfaceId: string; value?: unknown; path?: string | undefined; }; }, { version: "v1.0"; updateDataModel: { surfaceId: string; value?: unknown; path?: string | undefined; }; }>, z.ZodObject<{ version: z.ZodLiteral<"v1.0">; deleteSurface: z.ZodObject<{ surfaceId: z.ZodString; }, "strict", z.ZodTypeAny, { surfaceId: string; }, { surfaceId: string; }>; }, "strict", z.ZodTypeAny, { version: "v1.0"; deleteSurface: { surfaceId: string; }; }, { version: "v1.0"; deleteSurface: { surfaceId: string; }; }>, z.ZodObject<{ version: z.ZodLiteral<"v1.0">; functionCallId: z.ZodString; wantResponse: z.ZodOptional; callFunction: z.ZodObject<{ call: z.ZodString; catalogId: z.ZodOptional; args: z.ZodOptional>; }, "passthrough", z.ZodTypeAny, z.objectOutputType<{ call: z.ZodString; catalogId: z.ZodOptional; args: z.ZodOptional>; }, z.ZodTypeAny, "passthrough">, z.objectInputType<{ call: z.ZodString; catalogId: z.ZodOptional; args: z.ZodOptional>; }, z.ZodTypeAny, "passthrough">>; }, "strict", z.ZodTypeAny, { version: "v1.0"; functionCallId: string; callFunction: { call: string; catalogId?: string | undefined; args?: Record | undefined; } & { [k: string]: unknown; }; wantResponse?: boolean | undefined; }, { version: "v1.0"; functionCallId: string; callFunction: { call: string; catalogId?: string | undefined; args?: Record | undefined; } & { [k: string]: unknown; }; wantResponse?: boolean | undefined; }>, z.ZodObject<{ version: z.ZodLiteral<"v1.0">; actionId: z.ZodString; actionResponse: z.ZodEffects; error: z.ZodOptional; }, "strict", z.ZodTypeAny, { value?: unknown; error?: unknown; }, { value?: unknown; error?: unknown; }>, { value?: unknown; error?: unknown; }, { value?: unknown; error?: unknown; }>; }, "strict", z.ZodTypeAny, { version: "v1.0"; actionId: string; actionResponse: { value?: unknown; error?: unknown; }; }, { version: "v1.0"; actionId: string; actionResponse: { value?: unknown; error?: unknown; }; }>]>; type PrometheusA2uiV1Message = z.infer; type PrometheusA2uiV1FunctionCall = z.infer; type PrometheusA2uiV1ActionResponse = z.infer; interface PrometheusA2uiV1ActionMetadata { surfaceId: string; sourceComponentId: string; wantResponse: boolean; responsePath?: string; } type PrometheusA2uiErrorCode = "invalid-message" | "unsupported-protocol-version" | "component-not-allowed" | "runtime-disposed"; declare class PrometheusA2uiError extends Error { readonly code: PrometheusA2uiErrorCode; readonly cause?: unknown; constructor(code: PrometheusA2uiErrorCode, message: string, cause?: unknown); } type PrometheusA2uiMessageInput = readonly unknown[] | { readonly messages: readonly unknown[]; }; interface CreatePrometheusA2uiRuntimeOptions { /** Explicit catalogs advertised to and accepted from agents. */ catalogs?: readonly Catalog[]; /** Defaults to a deny-all policy; applications must install authority. */ actionPolicy?: A2uiActionPolicy; /** Receives the auditable outcome of every official client action. */ onActionDecision?: (decision: A2uiActionDecision) => void | Promise; /** Receives A2UI v1.0 renderer-to-agent action/function/error messages. */ onRendererMessage?: (message: PrometheusA2uiRendererMessage) => void | Promise; /** Application-owned implementation for v1.0 agent-initiated function calls. */ onFunctionCall?: (call: PrometheusA2uiV1FunctionCall) => unknown | Promise; } type PrometheusA2uiRendererMessage = { version: typeof PROMETHEUS_A2UI_RC_PROTOCOL_VERSION; action: A2uiClientAction & { wantResponse?: boolean; actionId?: string; }; } | { version: typeof PROMETHEUS_A2UI_RC_PROTOCOL_VERSION; functionResponse: { functionCallId: string; call: string; value: unknown; }; } | { version: typeof PROMETHEUS_A2UI_RC_PROTOCOL_VERSION; error: { code: string; message: string; functionCallId: string; }; }; /** * Thin lifecycle wrapper around the official A2UI v0.9 MessageProcessor. * It adds exact-version enforcement, catalog/component allowlisting, policy * dispatch, and a React-compatible subscription snapshot—never a second * protocol parser or surface model. */ declare class PrometheusA2uiRuntime { readonly processor: MessageProcessor; private readonly catalogs; private readonly actionPolicy; private readonly onActionDecision?; private readonly onRendererMessage?; private readonly onFunctionCall?; private readonly listeners; private readonly subscriptions; private snapshot; private disposed; private actionSequence; private readonly surfaceCatalogs; private readonly v1Surfaces; private readonly v1Actions; private readonly pendingActions; private readonly agUiActivitySurfaces; constructor(options?: CreatePrometheusA2uiRuntimeOptions); /** Validate and process official v0.9.1 or v1.0 RC messages in order. */ processMessages(input: PrometheusA2uiMessageInput): void; /** Consume the AG-UI 0.0.59 A2UI activity snapshot convention. */ processAgUiEvent(input: unknown): boolean; getSurface(id: string): SurfaceModel | undefined; getSurfaces: () => readonly SurfaceModel[]; getClientCapabilities(options?: { includeInlineCatalogs?: boolean; }): A2uiClientCapabilities; getClientDataModel(): A2uiClientDataModel | undefined; subscribe: (listener: () => void) => (() => void); dispose(): void; private forwardV1Action; private handleV1ProtocolMessage; private preflight; private assertAllowedComponents; private refreshSnapshot; private assertActive; } declare function createPrometheusA2uiRuntime(options?: CreatePrometheusA2uiRuntimeOptions): PrometheusA2uiRuntime; declare const ENTITY_GRAPH_A2UI_ACTIONS: { readonly upsert: "prometheus.entity.upsert"; readonly replace: "prometheus.entity.replace"; readonly remove: "prometheus.entity.remove"; readonly patch: "prometheus.entity.patch"; readonly unpatch: "prometheus.entity.unpatch"; readonly clearPatch: "prometheus.entity.clear-patch"; }; type EntityGraphA2uiActionName = (typeof ENTITY_GRAPH_A2UI_ACTIONS)[keyof typeof ENTITY_GRAPH_A2UI_ACTIONS]; interface EntityGraphA2uiEntityPolicy { /** Exact graph actions allowed for this entity type. */ actions: readonly EntityGraphA2uiActionName[]; /** Exact fields the agent may write or unpatch. */ fields: readonly string[]; } interface EntityGraphA2uiAuthorizationContext { actionName: EntityGraphA2uiActionName; entityType: string; entityId: string; tenantId?: string; fields: readonly string[]; rawContext: Record; } interface CreateEntityGraphA2uiActionPolicyOptions { /** Inject a store for isolation/testing; defaults to the canonical graph. */ graphStore?: GraphStore; /** Entity/action/field allowlist. Missing entity types fail closed. */ entities: Readonly>; /** Application-owned tenant/scope authorization. Required and fail-closed. */ authorize: (context: EntityGraphA2uiAuthorizationContext) => A2uiAuthorizationDecision | Promise; /** Required at runtime for destructive `replace` and `remove` actions. */ requestApproval?: (request: A2uiApprovalRequest) => boolean | Promise; onDecision?: (decision: A2uiActionDecision) => void | Promise; } /** * Build the stable surface-action to normalized-entity bridge. * * The helper owns store writes; renderer components only emit official A2UI * actions through their hooks/runtime. */ declare function createEntityGraphA2uiActionPolicy(options: CreateEntityGraphA2uiActionPolicyOptions): A2uiActionPolicy; interface PrometheusA2uiProviderProps { /** Runtime ownership stays with the application so lifecycle is explicit. */ runtime: PrometheusA2uiRuntime; children: ReactNode; } declare function PrometheusA2uiProvider({ runtime, children, }: PrometheusA2uiProviderProps): React.JSX.Element; /** Read the nearest official A2UI runtime. */ declare function usePrometheusA2uiRuntime(): PrometheusA2uiRuntime; /** Subscribe to the official processor's surface collection. */ declare function usePrometheusA2uiSurfaces(): readonly SurfaceModel[]; interface UsePrometheusA2uiResult { runtime: PrometheusA2uiRuntime; surfaces: readonly SurfaceModel[]; processMessages(input: PrometheusA2uiMessageInput): void; getClientCapabilities(options?: { includeInlineCatalogs?: boolean; }): A2uiClientCapabilities; getClientDataModel(): A2uiClientDataModel | undefined; } /** Orchestrate official message ingestion and surface reads from React. */ declare function usePrometheusA2ui(): UsePrometheusA2uiResult; interface PrometheusA2uiSurfaceProps { surfaceId: string; fallback?: ReactNode; className?: string; } /** Render one official catalog-backed A2UI surface. */ declare function PrometheusA2uiSurface({ surfaceId, fallback, className, }: PrometheusA2uiSurfaceProps): React.JSX.Element; interface PrometheusA2uiSurfacesProps { empty?: ReactNode; className?: string; surfaceClassName?: string; } /** Render every surface currently owned by the official processor. */ declare function PrometheusA2uiSurfaces({ empty, className, surfaceClassName, }: PrometheusA2uiSurfacesProps): React.JSX.Element; export { type A2uiActionDecision, type A2uiActionDeniedCode, type A2uiActionPolicy, type A2uiActionPolicyOptions, type A2uiActionRule, type A2uiApprovalRequest, type A2uiAuthorizationDecision, type CreateEntityGraphA2uiActionPolicyOptions, type CreatePrometheusA2uiRuntimeOptions, DEFAULT_PROMETHEUS_A2UI_COMPONENTS, DEFAULT_PROMETHEUS_A2UI_FUNCTIONS, ENTITY_GRAPH_A2UI_ACTIONS, type EntityGraphA2uiActionName, type EntityGraphA2uiAuthorizationContext, type EntityGraphA2uiEntityPolicy, PROMETHEUS_A2UI_CATALOG_ID, PROMETHEUS_A2UI_PROTOCOL_VERSION, PROMETHEUS_A2UI_RC_PROTOCOL_VERSION, type PrometheusA2uiCatalogOptions, type PrometheusA2uiComponentImplementation, type PrometheusA2uiComponentName, type PrometheusA2uiComponentRenderProps, PrometheusA2uiError, type PrometheusA2uiErrorCode, type PrometheusA2uiFunctionName, type PrometheusA2uiMessageInput, PrometheusA2uiProvider, type PrometheusA2uiProviderProps, type PrometheusA2uiRendererMessage, PrometheusA2uiRuntime, PrometheusA2uiSurface, type PrometheusA2uiSurfaceProps, PrometheusA2uiSurfaces, type PrometheusA2uiSurfacesProps, type PrometheusA2uiV1ActionMetadata, type PrometheusA2uiV1ActionResponse, type PrometheusA2uiV1FunctionCall, type PrometheusA2uiV1Message, type UsePrometheusA2uiResult, createA2uiActionPolicy, createDenyAllA2uiActionPolicy, createEntityGraphA2uiActionPolicy, createPrometheusA2uiCatalog, createPrometheusA2uiComponent, createPrometheusA2uiRuntime, getPrometheusA2uiOfficialComponent, usePrometheusA2ui, usePrometheusA2uiRuntime, usePrometheusA2uiSurfaces };