The Open Standard for Generative UI
Add standalone WithPreviewRenderer rendering (#1268)
ABf1f66c4266d6
diff --git a/.changeset/generalized-renderer.md b/.changeset/generalized-renderer.mdnew file mode 100644index 000000000..399f53928--- /dev/null+++ b/.changeset/generalized-renderer.md@@ -0,0 +1,9 @@+---+"@openuidev/react-lang": minor+"@openuidev/a2ui": minor+"@openuidev/server": minor+---++Add optional Renderer slots for content, query loading, errors, and retry controls. Keep `queryLoader` supported on `Renderer` and `A2UIRenderer`. Preserve the default loading spinner; error/retry views render nothing unless supplied by the application.++Preserve the existing query lifecycle while waiting for generation to finish. Keep mounted input state through retries and refresh query results when generated scripts change.diff --git a/docs/content/docs/api-reference/a2ui.mdx b/docs/content/docs/api-reference/a2ui.mdxindex aa7e2396f..83aaed8d0 100644--- a/docs/content/docs/api-reference/a2ui.mdx+++ b/docs/content/docs/api-reference/a2ui.mdx@@ -325,7 +325,7 @@ The component subscribes to the client with `useSyncExternalStore`, reads the re| `onError` | `(errors) => void` | Receives OpenUI parser/runtime errors || `formStateKeys` | `readonly string[]` | Adds top-level data-model keys that should also hydrate form namespaces || `toolProvider` | `RendererProps["toolProvider"]` | Overrides the default A2UI routing for OpenUI Lang `Query()` and `Mutation()` calls |-| `queryLoader` | `ReactNode` | UI shown while a query is loading |+| `children` | `React.ReactNode` | Optional Renderer slot composition; omit for default content, loading, and error views. |`@OpenUrl` is handled locally and is not emitted as an A2UI action. Other OpenUI actions are converted to A2UI actions automatically.diff --git a/docs/content/docs/api-reference/react-lang.mdx b/docs/content/docs/api-reference/react-lang.mdxindex 1a329b7d5..2f3552285 100644--- a/docs/content/docs/api-reference/react-lang.mdx+++ b/docs/content/docs/api-reference/react-lang.mdx@@ -106,11 +106,41 @@ interface RendererProps {| Record<string, (args: Record<string, unknown>) => Promise<unknown>>| McpClientLike| null;+ /** Custom loading indicator. Defaults to a spinner. */queryLoader?: React.ReactNode;+ children?: React.ReactNode;onError?: (errors: OpenUIError[]) => void;}```+## Renderer slots++`Renderer` keeps query defaults or cached results visible while loading and after failures, and reports errors through `onError`. A spinner is shown while queries load; provide `queryLoader` to customize it. No error/retry view is shown by default. To customize loading feedback and opt into an error/retry presentation, use `Renderer.Root` with these slots:++| Slot | Purpose |+| --- | --- |+| `Renderer.Content` | Generated UI; accepts div props and stays mounted during query failures. |+| `Renderer.QueryLoading` | Children shown while queries wait or fetch; omitted children use `queryLoader` or the default spinner. |+| `Renderer.QueryError` | Children shown when queries fail; renders nothing without children. |+| `Renderer.Retry` | A retry button; accepts standard button props. |++Root accepts the same runtime props as Renderer and renders only its children. Put overlays in your own positioned container. Slots share context through wrappers and React portals. `useRendererQuery()` returns `{ isLoading, errors, retry, isRetrying }` within that root. `Renderer.Content` renders defaults or cached data while queries load and hides content on failure while preserving mounted state through retries.++`Renderer` accepts slot children to replace its default content composition. Without children, Renderer keeps its default views. Calling `preventDefault()` in the retry button’s click handler cancels the retry.++```tsx+<Renderer.Root response={response} library={library} toolProvider={tools}>+ <div style={{ position: "relative" }}>+ <Renderer.Content />+ <Renderer.QueryLoading>Loading data…</Renderer.QueryLoading>+ <Renderer.QueryError>+ <p role="alert">Data is unavailable.</p>+ <Renderer.Retry>Try again</Renderer.Retry>+ </Renderer.QueryError>+ </div>+</Renderer.Root>+```+## Tool ProviderHandles `Query()` and `Mutation()` tool calls at runtime. The `toolProvider` prop accepts two forms:diff --git a/docs/content/docs/api-reference/server.mdx b/docs/content/docs/api-reference/server.mdxindex 8a7144857..658e8ad38 100644--- a/docs/content/docs/api-reference/server.mdx+++ b/docs/content/docs/api-reference/server.mdx@@ -3,7 +3,7 @@ title: "@openuidev/server"description: API reference for Autofix helpers and conversation history persistence on the OpenUI Gateway.----Server utilities for OpenUI Gateway. Validate and repair model-generated OpenUI Lang, and persist a completed turn as Conversations API items.+Server utilities for OpenUI Gateway. Validate and repair model-generated OpenUI Lang, and persist a completed turn as Conversations API items.Import from the subpath that matches your SDK. The helpers call [Autofix HTTP API](/docs/gateway/api/autofix).## Installdiff --git a/docs/content/docs/openui-lang/renderer.mdx b/docs/content/docs/openui-lang/renderer.mdxindex 51ee3aba2..d1e139ab1 100644--- a/docs/content/docs/openui-lang/renderer.mdx+++ b/docs/content/docs/openui-lang/renderer.mdx@@ -34,7 +34,8 @@ export function AssistantMessage({| `initialState` | `Record<string, any>` | Hydrates form state on load (e.g. from persisted message). || `onParseResult` | `(result: ParseResult \| null) => void` | Debug/inspect latest parse result. || `toolProvider` | `Record<string, (args: Record<string, unknown>) => Promise<unknown>> \| McpClientLike \| null` | Handles `Query()` / `Mutation()` tool calls. Pass a function map or an [MCP](https://modelcontextprotocol.io/docs/getting-started/intro) client. |-| `queryLoader` | `React.ReactNode` | Custom loading indicator shown while queries are fetching. Defaults to a spinner. |+| `queryLoader` | `React.ReactNode` | Custom loading indicator; defaults to a spinner. |+| `children` | `React.ReactNode` | Optional Renderer slot composition; omit to keep content visible with a loading indicator. || `onError` | `(errors: OpenUIError[]) => void` | Structured, LLM-friendly errors from the parser and query system. Suitable for automated correction loops. Called with `[]` when resolved. |## Connecting toolsdiff --git a/packages/a2ui/src/Renderer.tsx b/packages/a2ui/src/Renderer.tsxindex a3a3acfde..8bc544f73 100644--- a/packages/a2ui/src/Renderer.tsx+++ b/packages/a2ui/src/Renderer.tsx@@ -30,7 +30,9 @@ export interface A2UIRendererProps {/** Additional top-level data-model keys that should hydrate form namespaces. */formStateKeys?: readonly string[];toolProvider?: OpenUIRendererProps["toolProvider"];+ /** Custom loading indicator. Defaults to a spinner. */queryLoader?: OpenUIRendererProps["queryLoader"];+ children?: OpenUIRendererProps["children"];}function collectFormStateKeys(result: ParseResult | null): string[] {@@ -68,6 +70,7 @@ export function A2UIRenderer({formStateKeys,toolProvider,queryLoader,+ children,}: A2UIRendererProps) {const subscribe = useCallback((notify: () => void) => client.subscribe(notify), [client]);const getSnapshot = useCallback(() => client.getSurface(surfaceId), [client, surfaceId]);@@ -140,6 +143,7 @@ export function A2UIRenderer({onError={onError}toolProvider={toolProvider ?? agentToolProvider}queryLoader={queryLoader}+ children={children}/>);}diff --git a/packages/lang-core/src/telemetry/runtime.ts b/packages/lang-core/src/telemetry/runtime.tsindex 0eadf4abb..dde4b3853 100644--- a/packages/lang-core/src/telemetry/runtime.ts+++ b/packages/lang-core/src/telemetry/runtime.ts@@ -471,6 +471,7 @@ function getValidationErrorCounts(| "validation_error_count"> {const counts: Record<ValidationErrorCode, number> = {+ "type-mismatch": 0,"unknown-component": 0,"missing-required": 0,"null-required": 0,diff --git a/packages/react-lang/README.md b/packages/react-lang/README.mdindex 6a1b94f9b..5a60540db 100644--- a/packages/react-lang/README.md+++ b/packages/react-lang/README.md@@ -18,6 +18,37 @@ pnpm add @openuidev/react-lang**Peer dependencies:** `react >=19.0.0`+## Query failures++Without slot children, `Renderer` keeps query defaults or cached results visible while loading and after failures. A spinner is shown while queries load, and `onError` receives structured errors. Provide `queryLoader` to customize the indicator, or slot children for custom layouts. No error/retry view is shown by default.++Use slots to customize loading and failure views:++```tsx+<Renderer.Root response={response} library={library} toolProvider={toolProvider}>+ <div style={{ position: "relative" }}>+ <Renderer.Content />+ <Renderer.QueryLoading>Loading data…</Renderer.QueryLoading>+ <Renderer.QueryError>+ <div role="alert">+ <p>We couldn't load your data. Please try again.</p>+ <Renderer.Retry>Try again</Renderer.Retry>+ </div>+ </Renderer.QueryError>+ </div>+</Renderer.Root>+```++`Renderer.Root` owns one runtime and renders only its children. Slots can sit inside wrappers or portals under that root. `Renderer.Content` keeps generated components mounted while queries load or fail; failed results remain hidden until recovery. Omitting a slot omits its presentation. Plain `Renderer` supplies content and a loading indicator without hiding results on failure.++`Renderer.QueryLoading` shows its children while queries await generation or fetch data, unless failures are being displayed. Omit children to use `queryLoader`, falling back to the default spinner. Position custom overlays within your own relative container. `Renderer.QueryError` shows its children on failure and renders nothing without children. Add `Renderer.Retry` explicitly if you want a retry button. `Renderer.Retry` disables itself during loading and when no queries have failed. It accepts standard button props; its click handler can prevent the retry with `event.preventDefault()`.++Use `useRendererQuery()` inside the root to read `{ isLoading, errors, retry, isRetrying }` in your own components. Generation progress remains available through `useIsStreaming()`. Do not create another root for each slot.++`Renderer` accepts slot children to replace its default content composition.++While queries load, `Renderer.Content` renders their defaults or previously successful data. During streaming edits, previously loaded results remain visible with loading feedback until the updated response is ready.+## Overview`@openuidev/react-lang` is the React runtime layer for OpenUI Lang. It covers the loop most apps need:@@ -100,7 +131,7 @@ function AssistantMessage({ response, isStreaming }) {| Export | Description || :--- | :--- |-| `Renderer` | React component that parses and renders OpenUI Lang output |+| `Renderer` | Render OpenUI Lang |**`RendererProps`:**@@ -112,6 +143,7 @@ function AssistantMessage({ response, isStreaming }) {| `onAction` | `(event: ActionEvent) => void` | Callback when a component triggers an action || `onStateUpdate` | `(state: Record<string, any>) => void` | Callback when form field values change || `initialState` | `Record<string, any>` | Initial form state for hydration |+| `queryLoader` | `React.ReactNode` | Custom loading indicator; defaults to a spinner || `onParseResult` | `(result: ParseResult \| null) => void` | Callback when the parse result changes |### Parser (Server-Side)diff --git a/packages/react-lang/src/Renderer.tsx b/packages/react-lang/src/Renderer.tsxindex 669ddb5b5..df50ee11e 100644--- a/packages/react-lang/src/Renderer.tsx+++ b/packages/react-lang/src/Renderer.tsx@@ -7,13 +7,30 @@ import type {ToolProvider,} from "@openuidev/lang-core";import { ToolNotFoundError, extractToolResult } from "@openuidev/lang-core";-import React, { Component, Fragment, useEffect, useInsertionEffect, useRef } from "react";+import React, {+ Component,+ Fragment,+ createContext,+ useContext,+ useEffect,+ useInsertionEffect,+ useMemo,+ useRef,+} from "react";import { OpenUIContext, useOpenUI, useRenderNode } from "./context";import { useOpenUIState } from "./hooks/useOpenUIState";import type { ComponentRenderer, Library } from "./library";+export interface RendererQueryState {+ /** Whether any query is waiting for generation or fetching data. */+ isLoading: boolean;+ errors: OpenUIError[];+ retry: () => void;+ isRetrying: boolean;+}+export interface RendererProps {- /** Raw response text (openui-lang code). */+ /** OpenUI Lang code or the complete Cloud response bundle. */response: string | null;/** Component library from createLibrary(). */library: Library;@@ -41,12 +58,15 @@ export interface RendererProps {*/toolProvider?:Record<string, (args: Record<string, unknown>) => Promise<unknown>> | McpClientLike | null;- /** Custom loading indicator shown while queries are fetching. Defaults to a spinner. */+ /** Custom loading indicator. Defaults to a spinner. */queryLoader?: React.ReactNode;+ /** Custom slot composition. Omit to keep content visible with a loading indicator. */+ children?: React.ReactNode;/*** Called with structured, LLM-friendly errors from the parser and query system.- * Only includes errors fixable by changing the openui-lang code (unknown components,- * missing required props, tool-not-found). Suitable for an automated LLM correction loop.+ * Includes generation errors (unknown components, missing required props)+ * and tool execution failures. Retry data-source failures instead of treating+ * every query error as a reason to regenerate the program.* Called with [] when all errors are resolved.*/onError?: (errors: OpenUIError[]) => void;@@ -182,6 +202,8 @@ function ensureLoadingStyle() {const DefaultQueryLoader = () => (<div+ role="status"+ aria-label="Loading data"style={{position: "absolute",top: 8,@@ -197,7 +219,7 @@ const DefaultQueryLoader = () => (/>);-export function Renderer({+function RendererRoot({response,library,isStreaming = false,@@ -207,6 +229,7 @@ export function Renderer({onParseResult,toolProvider,queryLoader,+ children,onError,publishObservability,}: RendererProps) {@@ -245,20 +268,21 @@ export function Renderer({});const resolvedToolProvider = toolProvider != null ? stableToolProvider.current : null;- const { result, parseResult, contextValue, isQueryLoading } = useOpenUIState(- {- response,- library,- isStreaming,- onAction,- onStateUpdate,- initialState,- toolProvider: resolvedToolProvider,- onError,- publishObservability,- },- renderDeep,- );+ const { result, parseResult, contextValue, isQueryLoading, queryErrors, retryQueries } =+ useOpenUIState(+ {+ response,+ library,+ isStreaming,+ onAction,+ onStateUpdate,+ initialState,+ toolProvider: resolvedToolProvider,+ onError,+ publishObservability,+ },+ renderDeep,+ );// Fire onParseResult with the RAW parse result (not evaluated),// so hosts only see changes when the parser output actually changes.@@ -266,18 +290,132 @@ export function Renderer({onParseResultRef.current?.(parseResult);}, [parseResult]);- if (!result?.root) {- return null;- }+ const query = useMemo<RendererQueryState>(+ () => ({+ isLoading: isQueryLoading,+ errors: queryErrors,+ retry: retryQueries,+ isRetrying: queryErrors.length > 0 && isQueryLoading,+ }),+ [isQueryLoading, queryErrors, retryQueries],+ );+ const value = useMemo(+ () => ({ root: result?.root ?? null, query, queryLoader }),+ [result?.root, query, queryLoader],+ );return (<OpenUIContext.Provider value={contextValue}>- <div style={{ position: "relative" }}>- {isQueryLoading && (queryLoader ?? <DefaultQueryLoader />)}- <div style={{ opacity: isQueryLoading ? 0.7 : 1, transition: "opacity 0.2s ease" }}>- <RenderNode node={result.root} />- </div>- </div>+ <RendererContext.Provider value={value}>{children}</RendererContext.Provider></OpenUIContext.Provider>);}++const RendererContext = createContext<{+ root: ElementNode | null;+ query: RendererQueryState;+ queryLoader?: React.ReactNode;+} | null>(null);++function useRendererContext() {+ const context = useContext(RendererContext);+ if (!context) {+ throw new Error("Renderer slots must be used within Renderer.Root or Renderer.");+ }+ return context;+}++/** Access query loading, failures, and retry within the nearest Renderer root. */+export function useRendererQuery(): RendererQueryState {+ return useRendererContext().query;+}++export type RendererContentSlotProps = Omit<React.ComponentPropsWithRef<"div">, "children">;++/** Displays generated content, preserving mounted components while queries load or fail. */+function RendererContent({ style, hidden, ...props }: RendererContentSlotProps) {+ const { root, query } = useRendererContext();+ if (!root) return null;+ return (+ <div+ {...props}+ aria-busy={query.isLoading}+ hidden={hidden || query.errors.length > 0}+ style={{ opacity: query.isLoading ? 0.7 : 1, transition: "opacity 0.2s ease", ...style }}+ >+ <RenderNode node={root} />+ </div>+ );+}++export interface RendererSlotProps {+ children?: React.ReactNode;+}++/** Shows query loading feedback, except while a query failure is being displayed. */+function RendererQueryLoading({ children }: RendererSlotProps) {+ const {+ query: { isLoading, errors },+ queryLoader,+ } = useRendererContext();+ if (!isLoading || errors.length > 0) return null;+ return <>{children === undefined ? (queryLoader ?? <DefaultQueryLoader />) : children}</>;+}++/** Shows the supplied content when queries fail; renders nothing without children. */+function RendererQueryError({ children }: RendererSlotProps) {+ const { errors } = useRendererQuery();+ if (errors.length === 0) return null;+ return <>{children}</>;+}++export type RendererRetryProps = React.ComponentPropsWithRef<"button">;++function RendererRetry({ children, onClick, disabled, ...props }: RendererRetryProps) {+ const { retry, isLoading, errors } = useRendererQuery();+ const isDisabled = disabled || isLoading || errors.length === 0;+ return (+ <button+ type="button"+ {...props}+ disabled={isDisabled}+ onClick={(event: React.MouseEvent<HTMLButtonElement>) => {+ if (isDisabled || event.defaultPrevented) return;+ onClick?.(event);+ if (!event.defaultPrevented) retry();+ }}+ >+ {children}+ </button>+ );+}++function DefaultRendererContent() {+ const { root, query, queryLoader } = useRendererContext();+ if (!root) return null;+ return (+ <div aria-busy={query.isLoading} style={{ position: "relative" }}>+ {query.isLoading && (queryLoader ?? <DefaultQueryLoader />)}+ <div style={{ opacity: query.isLoading ? 0.7 : 1, transition: "opacity 0.2s ease" }}>+ <RenderNode node={root} />+ </div>+ </div>+ );+}++function DefaultRenderer({ children, ...props }: RendererProps) {+ return (+ <RendererRoot {...props}>+ {children === undefined ? <DefaultRendererContent /> : children}+ </RendererRoot>+ );+}++/** Render with the default presentation, or compose slots around one shared runtime. */+export const Renderer = Object.assign(DefaultRenderer, {+ Root: RendererRoot,+ Content: RendererContent,+ QueryLoading: RendererQueryLoading,+ QueryError: RendererQueryError,+ Retry: RendererRetry,+});diff --git a/packages/react-lang/src/WithPreviewRenderer.tsx b/packages/react-lang/src/WithPreviewRenderer.tsxnew file mode 100644index 000000000..582b1ccf8--- /dev/null+++ b/packages/react-lang/src/WithPreviewRenderer.tsx@@ -0,0 +1,192 @@+import {+ createContext,+ useCallback,+ useContext,+ useEffect,+ useId,+ useMemo,+ useRef,+ useState,+ type ComponentPropsWithRef,+} from "react";+import { Renderer, type RendererProps } from "./Renderer";+import { parseResponseBundle, type ResponseMetadata } from "./responseBundle";++export interface RendererPreviewState {+ metadata: ResponseMetadata;+ isOpen: boolean;+ isStreaming: boolean;+ /** ID of the expanded content region. */+ contentId: string;+ open: () => void;+ close: () => void;+}++export interface WithPreviewRendererProps extends RendererProps {+ /** Controlled visibility. Omit to use internal state. */+ open?: boolean;+ /** Initial visibility when uncontrolled. Defaults to false. */+ defaultOpen?: boolean;+ onOpenChange?: (open: boolean) => void;+ /** Metadata belongs to the preview presentation, not the underlying Renderer. */+ onMetadata?: (metadata: ResponseMetadata) => void;+ /** Compose Trigger, Content, and Close. Omit for the default preview and panel. */+ children?: React.ReactNode;+}++const PreviewContext = createContext<{+ state: RendererPreviewState;+ rendererProps: RendererProps;+} | null>(null);++function usePreviewContext() {+ const context = useContext(PreviewContext);+ if (!context) {+ throw new Error(+ "Preview slots must be used within WithPreviewRenderer.Root or WithPreviewRenderer.",+ );+ }+ return context;+}++/** Read metadata and control the nearest preview. Available even while its content is closed. */+export function useRendererPreview(): RendererPreviewState {+ return usePreviewContext().state;+}++function PreviewRoot({+ open: controlledOpen,+ defaultOpen = false,+ onOpenChange,+ onMetadata,+ children,+ ...rendererProps+}: WithPreviewRendererProps) {+ const [internalOpen, setInternalOpen] = useState(defaultOpen);+ const isOpen = controlledOpen ?? internalOpen;+ const isStreaming = rendererProps.isStreaming === true;+ const contentId = useId();+ const bundle = useMemo(+ () => parseResponseBundle(rendererProps.response, isStreaming),+ [rendererProps.response, isStreaming],+ );+ const metadataName = bundle.metadata.name;+ const metadata = useMemo<ResponseMetadata>(+ () => (metadataName === undefined ? {} : { name: metadataName }),+ [metadataName],+ );+ const metadataCallback = useRef(onMetadata);+ metadataCallback.current = onMetadata;+ useEffect(() => {+ metadataCallback.current?.(metadata);+ }, [metadata]);++ const setOpen = useCallback(+ (next: boolean) => {+ if (next === isOpen) return;+ if (controlledOpen === undefined) setInternalOpen(next);+ onOpenChange?.(next);+ },+ [controlledOpen, isOpen, onOpenChange],+ );+ const open = useCallback(() => setOpen(true), [setOpen]);+ const close = useCallback(() => setOpen(false), [setOpen]);+ const state = useMemo(+ () => ({ metadata, isOpen, isStreaming, contentId, open, close }),+ [metadata, isOpen, isStreaming, contentId, open, close],+ );++ return (+ <PreviewContext.Provider value={{ state, rendererProps }}>{children}</PreviewContext.Provider>+ );+}++export type PreviewButtonProps = ComponentPropsWithRef<"button">;++function PreviewTrigger({ children, onClick, disabled, ...props }: PreviewButtonProps) {+ const { metadata, isOpen, isStreaming, contentId, open, close } = useRendererPreview();+ return (+ <button+ type="button"+ {...props}+ disabled={disabled}+ aria-expanded={isOpen}+ aria-controls={isOpen ? contentId : undefined}+ onClick={(event) => {+ if (disabled || event.defaultPrevented) return;+ onClick?.(event);+ if (!event.defaultPrevented) (isOpen ? close : open)();+ }}+ >+ {children === undefined+ ? `${metadata.name || "Untitled artifact"}${isStreaming ? " (generating…)" : ""}`+ : children}+ </button>+ );+}++function PreviewClose({ children, onClick, disabled, ...props }: PreviewButtonProps) {+ const { metadata, close } = useRendererPreview();+ return (+ <button+ type="button"+ {...props}+ disabled={disabled}+ onClick={(event) => {+ if (disabled || event.defaultPrevented) return;+ onClick?.(event);+ if (!event.defaultPrevented) close();+ }}+ >+ {children === undefined ? `Close ${metadata.name || "Untitled artifact"}` : children}+ </button>+ );+}++export type PreviewContentProps = ComponentPropsWithRef<"section">;++/** Mount one content slot per preview. Query hooks and Renderer slots belong inside it. */+function PreviewContent({ children, style, ...props }: PreviewContentProps) {+ const { state, rendererProps } = usePreviewContext();+ if (!state.isOpen) return null;+ return (+ <section+ aria-label={state.metadata.name || "Untitled artifact"}+ {...props}+ id={state.contentId}+ style={{ position: "relative", ...style }}+ >+ {children === undefined ? (+ <>+ <PreviewClose />+ <Renderer {...rendererProps} />+ </>+ ) : (+ <Renderer {...rendererProps}>{children}</Renderer>+ )}+ </section>+ );+}++function DefaultWithPreviewRenderer({ children, ...props }: WithPreviewRendererProps) {+ return (+ <PreviewRoot {...props}>+ {children === undefined ? (+ <>+ <PreviewTrigger />+ <PreviewContent />+ </>+ ) : (+ children+ )}+ </PreviewRoot>+ );+}++/** Adds a preview and expandable content. Use Renderer for a directly visible interface. */+export const WithPreviewRenderer = Object.assign(DefaultWithPreviewRenderer, {+ Root: PreviewRoot,+ Trigger: PreviewTrigger,+ Content: PreviewContent,+ Close: PreviewClose,+});diff --git a/packages/react-lang/src/exports.ts b/packages/react-lang/src/exports.tsindex 586c5ef99..2a2beb30e 100644--- a/packages/react-lang/src/exports.ts+++ b/packages/react-lang/src/exports.ts@@ -14,8 +14,14 @@ export type {} from "./library";// openui-lang renderer-export { Renderer } from "./Renderer";-export type { RendererProps } from "./Renderer";+export { Renderer, useRendererQuery } from "./Renderer";+export type {+ RendererContentSlotProps,+ RendererProps,+ RendererQueryState,+ RendererRetryProps,+ RendererSlotProps,+} from "./Renderer";// openui-lang action typesexport { ACTION_STEPS, BuiltinActionType } from "@openuidev/lang-core";@@ -86,3 +92,12 @@ export {validate,} from "@openuidev/lang-core";export type { ParsedRule, ValidatorFn } from "@openuidev/lang-core";++export type { ResponseMetadata } from "./responseBundle";+export { WithPreviewRenderer, useRendererPreview } from "./WithPreviewRenderer";+export type {+ PreviewButtonProps,+ PreviewContentProps,+ RendererPreviewState,+ WithPreviewRendererProps,+} from "./WithPreviewRenderer";diff --git a/packages/react-lang/src/hooks/useOpenUIState.ts b/packages/react-lang/src/hooks/useOpenUIState.tsindex 13df4cde6..7ff171c01 100644--- a/packages/react-lang/src/hooks/useOpenUIState.ts+++ b/packages/react-lang/src/hooks/useOpenUIState.ts@@ -21,6 +21,7 @@ import type React from "react";import { useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from "react";import type { OpenUIContextValue } from "../context";import type { Library } from "../library";+import { parseResponseBundle } from "../responseBundle";import { useOpenUIErrors } from "./useOpenUIErrors";import { useStreamingObservability } from "./useStreamingObservability";@@ -59,6 +60,9 @@ export interface OpenUIState {contextValue: OpenUIContextValue;/** Whether any Query is currently fetching data. */isQueryLoading: boolean;+ /** Failed queries whose fallback values must not be presented as current data. */+ queryErrors: OpenUIError[];+ retryQueries: () => void;}/**@@ -82,16 +86,33 @@ export function useOpenUIState(}: UseOpenUIStateOptions,renderDeep: (value: unknown) => React.ReactNode,): OpenUIState {+ const bundle = useMemo(() => parseResponseBundle(response, isStreaming), [response, isStreaming]);+ const blocked = isStreaming || !bundle.complete || !!bundle.error;+ // Bare DSL keeps its existing manager, cached results and imperative actions while streaming.+ const bundleBlocked = bundle.isBundle && blocked;+ // Keep the last completed script revision while an edit streams its base and patches.+ const settledScripts = useRef({ revision: null as string | null, names: new Set<string>() });+ if (!blocked) {+ settledScripts.current = {+ revision: "scriptRevision" in bundle ? (bundle.scriptRevision ?? null) : null,+ names: bundle.scripts,+ };+ }+ const scriptRevision = settledScripts.current.revision;+ const scriptNames = settledScripts.current.names;+// ─── Streaming parser (incremental — caches completed statements) ───const sp = useMemo(() => createStreamingParser(library.toJSONSchema(), library.root), [library]);// ─── Parse result ───const parseExceptionRef = useRef<OpenUIError | null>(null);const result = useMemo<ParseResult | null>(() => {- parseExceptionRef.current = null;- if (!response) return null;+ parseExceptionRef.current = bundle.error+ ? { source: "parser", code: "parse-failed", message: bundle.error }+ : null;+ if (!bundle.program) return null;try {- return sp.set(response);+ return sp.set(bundle.program);} catch (e) {const msg = e instanceof Error ? e.message : String(e);parseExceptionRef.current = {@@ -102,7 +123,7 @@ export function useOpenUIState(};return null;}- }, [sp, response]);+ }, [sp, bundle.program, bundle.error]);// ─── Store (holds everything: $bindings + form fields) ───const store = useMemo<Store>(() => createStore(), []);@@ -164,19 +185,22 @@ export function useOpenUIState(// ─── Evaluate and submit queries ───useEffect(() => {- if (isStreaming) return;+ // Keep the existing query lifecycle until streaming finishes and the bundle is ready.+ if (blocked) return;const queryStmts = result?.queryStatements ?? [];const evaluatedNodes = queryStmts.map((qn) => {const relevantDeps: Record<string, unknown> = {};+ const toolName = qn.toolAST ? (evaluate(qn.toolAST, evaluationContext) as string) : "";if (qn.deps) {for (const ref of qn.deps) {relevantDeps[ref] = storeSnapshot[ref];}}+ if (scriptNames.has(toolName)) relevantDeps.__openuiScriptRevision = scriptRevision;return {statementId: qn.statementId,- toolName: qn.toolAST ? (evaluate(qn.toolAST, evaluationContext) as string) : "",+ toolName,args: qn.argsAST ? evaluate(qn.argsAST, evaluationContext) : null,defaults: qn.defaultsAST ? evaluate(qn.defaultsAST, evaluationContext) : null,refreshInterval: qn.refreshAST@@ -189,11 +213,19 @@ export function useOpenUIState(// Always call — empty array clears removed queries and their errorsqueryManager.evaluateQueries(evaluatedNodes);- }, [isStreaming, result?.queryStatements, evaluationContext, queryManager, storeSnapshot]);+ }, [+ blocked,+ result?.queryStatements,+ evaluationContext,+ queryManager,+ storeSnapshot,+ scriptRevision,+ scriptNames,+ ]);// ─── Register mutations ───useEffect(() => {- if (isStreaming) return;+ if (blocked) return;const mutStmts = result?.mutationStatements ?? [];const nodes = mutStmts.map((mn) => ({@@ -202,7 +234,7 @@ export function useOpenUIState(}));// Always call — empty array clears removed mutations and their errorsqueryManager.registerMutations(nodes);- }, [isStreaming, result?.mutationStatements, evaluationContext, queryManager]);+ }, [blocked, result?.mutationStatements, evaluationContext, queryManager]);// ─── Ref for stable callbacks ───const propsRef = useRef({ onAction, onStateUpdate });@@ -283,6 +315,7 @@ export function useOpenUIState(formName?: string,action?: ActionPlan | { type?: string; params?: Record<string, any> },) => {+ if (bundleBlocked) return;const formPayload = getFormPayload(formName);const { onAction: handler } = propsRef.current;@@ -371,7 +404,7 @@ export function useOpenUIState(formName,});},- [queryManager, evaluationContext, getFormPayload, store],+ [bundleBlocked, queryManager, evaluationContext, getFormPayload, store],);// ─── reportError (for error boundary) ───@@ -384,35 +417,17 @@ export function useOpenUIState(renderErrorsRef.current.push(error);}, []);- const isQueryLoading = querySnapshot.__openui_loading.length > 0;-- // ─── Context value ───- const contextValue = useMemo<OpenUIContextValue>(- () => ({- library,- renderNode: renderDeep,- triggerAction,- isStreaming,- getFieldValue,- setFieldValue,- store,- evaluationContext,- reportError,- isQueryLoading,- }),- [- library,- renderDeep,- isStreaming,- isQueryLoading,- triggerAction,- getFieldValue,- setFieldValue,- store,- evaluationContext,- reportError,- ],+ const isQueryLoading =+ querySnapshot.__openui_loading.length > 0 ||+ (isStreaming && bundleBlocked && (result?.queryStatements.length ?? 0) > 0);+ const queryErrors = useMemo(+ () => querySnapshot.__openui_errors.filter((error) => error.source === "query"),+ [querySnapshot],);+ const retryQueries = useCallback(() => {+ if (bundleBlocked) return;+ queryManager.invalidate(queryErrors.map((error) => error.statementId!));+ }, [bundleBlocked, queryManager, queryErrors]);// ─── Evaluate props ───const runtimeErrorsRef = useRef<OpenUIError[]>([]);@@ -439,6 +454,33 @@ export function useOpenUIState(}}, [result, evaluationContext, library, store, storeSnapshot, querySnapshot]);+ const contextValue = useMemo<OpenUIContextValue>(+ () => ({+ library,+ renderNode: renderDeep,+ triggerAction,+ isStreaming: blocked,+ getFieldValue,+ setFieldValue,+ store,+ evaluationContext,+ reportError,+ isQueryLoading,+ }),+ [+ library,+ renderDeep,+ blocked,+ isQueryLoading,+ triggerAction,+ getFieldValue,+ setFieldValue,+ store,+ evaluationContext,+ reportError,+ ],+ );+// Keep error collection first: its effect refreshes this ref before the// observability effect publishes the terminal stream event.const { errorsRef, errorRevision } = useOpenUIErrors({@@ -455,7 +497,7 @@ export function useOpenUIState(});useStreamingObservability({- response,+ response: bundle.program,isStreaming,result,errorsRef,@@ -464,5 +506,12 @@ export function useOpenUIState(__libraryId: library.__libraryId,});- return { result: evaluatedResult, parseResult: result, contextValue, isQueryLoading };+ return {+ result: evaluatedResult,+ parseResult: result,+ contextValue,+ isQueryLoading,+ queryErrors,+ retryQueries,+ };}diff --git a/packages/react-lang/src/responseBundle.test.ts b/packages/react-lang/src/responseBundle.test.tsnew file mode 100644index 000000000..532667804--- /dev/null+++ b/packages/react-lang/src/responseBundle.test.ts@@ -0,0 +1,244 @@+import { describe, expect, it } from "vitest";+import { parseResponseBundle } from "./responseBundle";++const program = '```openui-lang\nroot = Text("Hello")\n```\n';+const script = { name: "sales_total", code: "async ({ tools }) => tools.get_sales({})" };++function scriptsSection(values: unknown, count: unknown = 1) {+ return `]]>openui:scripts ${JSON.stringify({ count })}\n${JSON.stringify(values)}\n`;+}++describe("parseResponseBundle", () => {+ describe("plain programs", () => {+ it.each([null, "", " \n", 'root = Text("Hello")', program])(+ "preserves an unframed response: %j",+ (response) => {+ for (const streaming of [false, true]) {+ expect(parseResponseBundle(response, streaming)).toEqual({+ program: response ?? "",+ metadata: {},+ scripts: new Set(),+ complete: true,+ isBundle: false,+ error: undefined,+ });+ }+ },+ );+ });++ describe("content and metadata", () => {+ it("decodes the optional name and separates the program from its envelope", () => {+ const response = ` \n]]>openui:content?thesys=true&name=Sales+%26+Growth+%E2%82%AC\n${program}]]>openui:end\n`;++ expect(parseResponseBundle(response, false)).toEqual({+ program,+ metadata: { name: "Sales & Growth €" },+ scripts: new Set(),+ complete: true,+ isBundle: true,+ error: undefined,+ });+ });++ it("accepts a bundle without metadata or scripts", () => {+ const response = `]]>openui:content\n${program}]]>openui:end`;++ expect(parseResponseBundle(response, false)).toMatchObject({+ program,+ metadata: {},+ complete: true,+ error: undefined,+ });+ });++ it("handles Windows line endings", () => {+ const response = `]]>openui:content?name=Sales\r\n${program.replaceAll("\n", "\r\n")}${scriptsSection([script]).replaceAll("\n", "\r\n")}]]>openui:end\r\n`;++ expect(parseResponseBundle(response, false)).toMatchObject({+ program: program.replaceAll("\n", "\r\n"),+ metadata: { name: "Sales" },+ scripts: new Set(["sales_total"]),+ complete: true,+ error: undefined,+ });+ });++ it("uses the latest content section without retaining old scripts or metadata", () => {+ const previous = `]]>openui:content?name=Previous\n${program}${scriptsSection([script])}]]>openui:end\n`;+ const replacement = 'root = Text("Updated")\n';+ const response = `${previous}]]>openui:content\n${replacement}]]>openui:end`;++ expect(parseResponseBundle(response, false)).toEqual({+ program: replacement,+ metadata: {},+ scripts: new Set(),+ complete: true,+ isBundle: true,+ error: undefined,+ });+ });+ });++ describe("scripts", () => {+ it("extracts script names without including script definitions in the program", () => {+ const values = [script, { name: "save_sales", code: "async () => null" }];+ const response = `]]>openui:content\n${program}${scriptsSection(values, 2)}]]>openui:end`;++ expect(parseResponseBundle(response, false)).toMatchObject({+ program,+ scripts: new Set(["sales_total", "save_sales"]),+ complete: true,+ error: undefined,+ });+ });++ it("accepts an explicitly empty scripts section", () => {+ const response = `]]>openui:content\n${program}${scriptsSection([], 0)}]]>openui:end`;++ expect(parseResponseBundle(response, false)).toMatchObject({+ scripts: new Set(),+ complete: true,+ error: undefined,+ });+ });++ it.each(["", "]]>openui:end"])("accepts a legacy script bundle with end marker %j", (end) => {+ const response = `${program}${scriptsSection([script])}${end}`;++ expect(parseResponseBundle(response, false)).toMatchObject({+ program,+ isBundle: true,+ scripts: new Set(["sales_total"]),+ complete: true,+ error: undefined,+ });+ });++ it.each([+ ["non-array payload", {}, 1],+ ["null payload", null, 1],+ ["mismatched count", [script], 2],+ ["string count", [script], "1"],+ ["fractional count", [script], 1.5],+ ["negative count", [], -1],+ ["null entry", [null], 1],+ ["missing name", [{ code: "async () => null" }], 1],+ ["empty name", [{ ...script, name: "" }], 1],+ ["non-string name", [{ ...script, name: 42 }], 1],+ ["missing code", [{ name: "sales_total" }], 1],+ ["non-string code", [{ ...script, code: 42 }], 1],+ ["duplicate names", [script, script], 2],+ ])("rejects %s after streaming finishes", (_label, values, count) => {+ const response = `]]>openui:content\n${program}${scriptsSection(values, count)}]]>openui:end`;++ expect(parseResponseBundle(response, false)).toMatchObject({+ program,+ complete: false,+ error: "Invalid scripts bundle",+ });+ expect(parseResponseBundle(response, true)).toMatchObject({+ program,+ complete: false,+ error: undefined,+ });+ });++ it.each(["]]>openui:scripts {invalid}\n[]\n", ']]>openui:scripts {"count":1}\n[{"name":\n'])(+ "rejects malformed script JSON: %j",+ (section) => {+ const response = `]]>openui:content\n${program}${section}]]>openui:end`;++ expect(parseResponseBundle(response, false)).toMatchObject({+ program,+ complete: false,+ error: "Invalid scripts bundle",+ });+ },+ );+ });++ describe("streaming and incomplete responses", () => {+ it("keeps every partial chunk error-free and exposes the program progressively", () => {+ const header = "]]>openui:content?name=Sales\n";+ const response = `${header}${program}${scriptsSection([script])}]]>openui:end`;++ for (let length = 1; length <= response.length; length++) {+ const parsed = parseResponseBundle(response.slice(0, length), true);+ expect(parsed.error, `prefix length ${length}`).toBeUndefined();+ expect(parsed.complete, `prefix length ${length}`).toBe(length === response.length);+ expect(parsed.isBundle).toBe(true);+ const visibleLength = Math.max(0, Math.min(program.length, length - header.length));+ expect(parsed.program).toBe(program.slice(0, visibleLength));+ }+ });++ it.each(["]]", "]]>openui:content?name=Sales"])(+ "reports an unfinished header only when streaming stops: %j",+ (response) => {+ expect(parseResponseBundle(response, true)).toMatchObject({+ program: "",+ complete: false,+ error: undefined,+ });+ expect(parseResponseBundle(response, false)).toMatchObject({+ program: "",+ complete: false,+ error: "Incomplete response header",+ });+ },+ );++ it.each([+ "",+ "]]>openui:scripts",+ scriptsSection([script]),+ "]]>openui:unknown",+ "]]>openui:end\nunexpected content",+ ])("does not mark an unfinished or invalid envelope complete: %j", (tail) => {+ const response = `]]>openui:content\n${program}${tail}`;++ expect(parseResponseBundle(response, false)).toMatchObject({+ program,+ complete: false,+ error: "Incomplete response bundle",+ });+ });+ });++ describe("markers inside content", () => {+ it.each([+ 'root = Text("]]>openui:scripts")\n',+ "root = Text(']]>openui:end')\n",+ String.raw`root = Text("An escaped quote: \" and marker: ]]>openui:end")` + "\n",+ String.raw`root = Text("A trailing backslash: \\")` + "\n",+ '// Ignore "]]>openui:scripts\nroot = Text("Hello")\n',+ '# Ignore \' ]]>openui:end\nroot = Text("Hello")\n',+ ])("preserves literal markers and comments: %j", (content) => {+ expect(parseResponseBundle(content, false)).toMatchObject({+ program: content,+ isBundle: false,+ error: undefined,+ });+ expect(+ parseResponseBundle(`]]>openui:content\n${content}]]>openui:end`, false),+ ).toMatchObject({+ program: content,+ complete: true,+ error: undefined,+ });+ });++ it("does not treat marker text inside script code as the end of the payload", () => {+ const code = String.raw`async () => "Escaped quote: \"; ]]>openui:end; ]]>openui:scripts"`;+ const response = `]]>openui:content\n${program}${scriptsSection([{ ...script, code }])}]]>openui:end`;++ expect(parseResponseBundle(response, false)).toMatchObject({+ program,+ scripts: new Set(["sales_total"]),+ complete: true,+ error: undefined,+ });+ });+ });+});diff --git a/packages/react-lang/src/responseBundle.ts b/packages/react-lang/src/responseBundle.tsnew file mode 100644index 000000000..3135cd02c--- /dev/null+++ b/packages/react-lang/src/responseBundle.ts@@ -0,0 +1,125 @@+/** Metadata emitted by OpenUI Cloud. */+export interface ResponseMetadata {+ name?: string;+}++const CONTENT = "]]>openui:content";+const SCRIPTS = "]]>openui:scripts";+const END = "]]>openui:end";++// Markers inside DSL/JSON strings are ordinary content.+function markerIndex(text: string, partial = false): number {+ let quote = "";+ let escaped = false;+ for (let i = 0; i < text.length; i++) {+ const c = text[i];+ if (quote) {+ if (escaped) escaped = false;+ else if (c === "\\") escaped = true;+ else if (c === quote) quote = "";+ } else if (c === "#" || (c === "/" && text[i + 1] === "/")) {+ const newline = text.indexOf("\n", i);+ if (newline < 0) return -1;+ i = newline;+ } else if (c === '"' || c === "'") quote = c;+ else if (text.startsWith("]]>", i) || (partial && "]]>".startsWith(text.slice(i)))) return i;+ }+ return -1;+}++export function parseResponseBundle(response: string | null, streaming: boolean) {+ let program = response ?? "";+ const metadata: ResponseMetadata = {};+ const scripts = new Set<string>();+ let scriptRevision: string | undefined;+ let error: string | undefined;+ let complete = true;+ let framed = false;+ let body = program.trimStart();+ if (body && (body.startsWith(CONTENT) || CONTENT.startsWith(body))) {+ framed = true;+ // A new content section replaces a progressive preview or failed retry.+ const sections = [...body.matchAll(/^\]\]>openui:content(?:\?[^\r\n]*)?\r?$/gm)];+ const last = sections[sections.length - 1];+ if (last) body = body.slice(last.index);+ const newline = body.indexOf("\n");+ if (newline < 0)+ return {+ isBundle: true,+ program: "",+ metadata,+ scripts,+ complete: false,+ error: streaming ? undefined : "Incomplete response header",+ };+ const header = body.slice(0, newline).trimEnd();+ const name = new URLSearchParams(header.slice(CONTENT.length).replace(/^\?/, "")).get("name");+ if (name !== null) metadata.name = name;+ body = body.slice(newline + 1);+ }+ program = body;+ const marker = markerIndex(body, framed && streaming);+ const isBundle = framed || marker >= 0;+ if (!isBundle) {+ return { program: response ?? "", metadata, scripts, complete, isBundle, error };+ }+ if (marker >= 0) {+ program = body.slice(0, marker);+ let tail = body.slice(marker).trimEnd();+ if (tail.startsWith(SCRIPTS)) {+ complete = false;+ const newline = tail.indexOf("\n");+ if (newline >= 0) {+ try {+ const header = JSON.parse(tail.slice(SCRIPTS.length, newline));+ let payload = tail.slice(newline + 1);+ const end = markerIndex(payload);+ if (end >= 0) {+ tail = payload.slice(end).trim();+ payload = payload.slice(0, end);+ } else tail = "";+ const values: unknown = JSON.parse(payload);+ if (+ !Array.isArray(values) ||+ !Number.isSafeInteger(header.count) ||+ header.count !== values.length+ )+ throw new Error("Invalid script count");+ for (const script of values) {+ if (+ !script ||+ typeof script.name !== "string" ||+ !script.name ||+ typeof script.code !== "string" ||+ scripts.has(script.name)+ )+ throw new Error("Invalid or duplicate script definition");+ scripts.add(script.name);+ }+ scriptRevision = JSON.stringify(+ values+ .map((script) => ({ name: script.name as string, code: script.code as string }))+ .sort((a, b) => a.name.localeCompare(b.name)),+ );+ complete = framed ? tail === END : tail === "" || tail === END;+ if (!complete) error = "Incomplete response bundle";+ } catch {+ error = "Invalid scripts bundle";+ }+ }+ } else {+ complete = tail === END;+ if (!complete) error = "Incomplete response bundle";+ }+ } else if (framed) complete = false;+ if (!complete && !streaming) error ??= "Incomplete response bundle";+ return {+ program,+ metadata,+ scripts,+ complete,+ isBundle,+ error: streaming ? undefined : error,+ ...(scripts.size ? { scriptRevision } : {}),+ };+}diff --git a/packages/server/src/shared/abort.ts b/packages/server/src/shared/abort.tsnew file mode 100644index 000000000..ba7820059--- /dev/null+++ b/packages/server/src/shared/abort.ts@@ -0,0 +1,14 @@+/** Stop waiting even when an upstream request or customer tool ignores cancellation. */+export async function abortable<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {+ signal.throwIfAborted();+ let abort!: () => void;+ const cancelled = new Promise<never>((_, reject) => {+ abort = () => reject(signal.reason);+ signal.addEventListener("abort", abort, { once: true });+ });+ try {+ return await Promise.race([promise, cancelled]);+ } finally {+ signal.removeEventListener("abort", abort);+ }+}diff --git a/packages/server/src/tools/execute.ts b/packages/server/src/tools/execute.tsnew file mode 100644index 000000000..e3d887923--- /dev/null+++ b/packages/server/src/tools/execute.ts@@ -0,0 +1,228 @@+import { abortable } from "../shared/abort";+import { THESYS_API_BASE_URL } from "../shared/constants";+import {+ ToolExecutionError,+ type RegisteredTools,+ type ScriptToolCall,+ type ScriptToolResult,+ type ToolExecutionOptions,+ type ToolExecutionRequest,+ type ToolExecutorOptions,+} from "./types";++const MAX_ROUNDS = 8;+const MAX_TOOL_CALLS = 16;+const DEFAULT_TIMEOUT_MS = 60_000;++const isRecord = (value: unknown): value is Record<string, unknown> =>+ value !== null && typeof value === "object" && !Array.isArray(value);++function invalidResponse(): never {+ throw new ToolExecutionError("Invalid script execution response", "invalid_response", 502);+}++/** Register server tools once, then execute direct tools or generated script loops. */+export function createToolExecutor<Context = undefined>(+ options: ToolExecutorOptions<Context>,+): RegisteredTools<Context> {+ const entries = Object.entries(options.tools);+ const tools = Object.fromEntries(entries.map(([name, tool]) => [name, tool.execute]));+ const definitions = entries.map(([name, { description, parameters, output }]) => ({+ name,+ parameters,+ ...(description !== undefined && { description }),+ ...(output !== undefined && { output }),+ }));+ const endpoint = `${(options.apiBaseUrl ?? THESYS_API_BASE_URL).replace(/\/+$/, "")}/v1/app/execute`;+ const fetchFn = options.fetch ?? globalThis.fetch;+ const apiKey = options.apiKey;++ async function execute(+ input: ToolExecutionRequest,+ executionOptions?: ToolExecutionOptions<Context>,+ ): Promise<unknown> {+ if (!input || typeof input.name !== "string" || !input.name) {+ throw new ToolExecutionError("A tool name is required", "invalid_input");+ }+ const args = input.arguments ?? {};+ if (!isRecord(args))+ throw new ToolExecutionError("Tool arguments must be an object", "invalid_input");+ const timeoutMs = executionOptions?.timeoutMs ?? DEFAULT_TIMEOUT_MS;+ if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {+ throw new ToolExecutionError("timeoutMs must be a positive finite number", "invalid_input");+ }+ executionOptions?.signal?.throwIfAborted();+ const controller = new AbortController();+ const forwardAbort = () => controller.abort(executionOptions?.signal?.reason);+ executionOptions?.signal?.addEventListener("abort", forwardAbort, { once: true });+ const timer = setTimeout(+ () =>+ controller.abort(new ToolExecutionError("Tool execution timed out", "tool_timeout", 504)),+ timeoutMs,+ );+ const signal = controller.signal;++ const dispatch = async (name: string, toolArgs: Record<string, unknown>) => {+ signal.throwIfAborted();+ if (!Object.hasOwn(tools, name) || typeof tools[name] !== "function") {+ throw new ToolExecutionError(`Unknown customer tool: ${name}`, "tool_not_found", 404);+ }+ return abortable(+ Promise.resolve().then(() =>+ tools[name]!(toolArgs, { context: executionOptions?.context as Context, signal }),+ ),+ signal,+ );+ };++ try {+ if (Object.hasOwn(tools, input.name)) return await dispatch(input.name, args);+ if (typeof input.response !== "string" || !input.response.trim()) {+ throw new ToolExecutionError(+ `Unknown tool: ${input.name}. Supply a complete OpenUI response for script execution.`,+ "tool_not_found",+ 404,+ );+ }++ if (!apiKey?.trim()) {+ throw new ToolExecutionError(+ "Pass apiKey to createToolExecutor to execute generated scripts",+ "missing_api_key",+ );+ }++ let state: string | undefined;+ let toolResults: ScriptToolResult[] = [];+ const seen = new Set<string>();+ // Allow a final settlement request after the last tool-call round.+ for (let round = 0; round <= MAX_ROUNDS; round++) {+ const response = await abortable(+ executeRound(+ {+ response: input.response,+ name: input.name,+ arguments: args,+ tool_results: toolResults,+ ...(state !== undefined && { state }),+ },+ signal,+ ),+ signal,+ );+ if (!isRecord(response)) invalidResponse();+ if (response["status"] === "done") return response["result"];+ if (response["status"] === "error") {+ const error = response["error"];+ if (+ !isRecord(error) ||+ typeof error["code"] !== "string" ||+ typeof error["message"] !== "string"+ )+ invalidResponse();+ // Never replay tools after a failed snapshot: a prior call may have mutated data.+ throw new ToolExecutionError(error["message"], error["code"]);+ }+ const calls = response["calls"];+ if (+ response["status"] !== "tool_calls" ||+ typeof response["state"] !== "string" ||+ !response["state"] ||+ !Array.isArray(calls) ||+ !calls.length+ )+ invalidResponse();+ if (round === MAX_ROUNDS || seen.size + calls.length > MAX_TOOL_CALLS) {+ throw new ToolExecutionError("Script execution limit exceeded", "script_limit", 502);+ }+ // Validate the complete batch before any customer tool starts.+ for (const call of calls) {+ if (+ !isRecord(call) ||+ (call["type"] !== undefined && call["type"] !== "function_call") ||+ typeof call["call_id"] !== "string" ||+ !call["call_id"] ||+ seen.has(call["call_id"]) ||+ typeof call["name"] !== "string" ||+ !call["name"] ||+ typeof call["arguments"] !== "string"+ )+ invalidResponse();+ seen.add(call["call_id"]);+ }+ state = response["state"];+ toolResults = await Promise.all(+ (calls as ScriptToolCall[]).map(async (call): Promise<ScriptToolResult> => {+ try {+ const toolArgs: unknown = JSON.parse(call.arguments);+ if (!isRecord(toolArgs))+ throw new ToolExecutionError("Tool arguments must be an object", "bad_args");+ const result = await dispatch(call.name, toolArgs);+ signal.throwIfAborted();+ const output = JSON.stringify(result ?? null);+ if (output === undefined)+ throw new ToolExecutionError(+ "Tool result must be JSON serializable",+ "bad_tool_result",+ );+ return {+ type: "function_call_output",+ call_id: call.call_id,+ output,+ };+ } catch (error) {+ signal.throwIfAborted();+ return {+ call_id: call.call_id,+ error: {+ code: error instanceof ToolExecutionError ? error.code : "tool_exec_error",+ message: error instanceof Error ? error.message : String(error),+ },+ };+ }+ }),+ );+ }+ throw new ToolExecutionError("Script execution limit exceeded", "script_limit", 502);+ } finally {+ clearTimeout(timer);+ executionOptions?.signal?.removeEventListener("abort", forwardAbort);+ controller.abort();+ }+ }++ async function executeRound(body: unknown, signal: AbortSignal): Promise<unknown> {+ signal.throwIfAborted();+ const response = await fetchFn(endpoint, {+ method: "POST",+ headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },+ body: JSON.stringify(body),+ signal,+ });+ let result: unknown;+ try {+ result = await response.json();+ } catch {+ signal.throwIfAborted();+ throw new ToolExecutionError(+ `Could not read script execution response (HTTP ${response.status})`,+ "invalid_response",+ response.status,+ );+ }+ signal.throwIfAborted();+ if (!response.ok) {+ const error = isRecord(result) && isRecord(result["error"]) ? result["error"] : undefined;+ throw new ToolExecutionError(+ typeof error?.["message"] === "string"+ ? error["message"]+ : `Script execution failed: HTTP ${response.status}`,+ typeof error?.["code"] === "string" ? error["code"] : "http_error",+ response.status,+ );+ }+ return result;+ }++ return { definitions, execute };+}diff --git a/packages/server/src/tools/types.ts b/packages/server/src/tools/types.tsnew file mode 100644index 000000000..677963bb6--- /dev/null+++ b/packages/server/src/tools/types.ts@@ -0,0 +1,73 @@+/** Provider-neutral metadata passed to generation, without server handlers. */+export interface ToolDefinition {+ name: string;+ description?: string;+ parameters: Record<string, unknown>;+ /** Illustrative output for generation; the handler supplies actual runtime data. */+ output?: unknown;+}++/** Registered customer tools execute on the host server with trusted context. */+export type ToolHandler<Context = undefined> = (+ args: Record<string, unknown>,+ options: { context: Context; signal: AbortSignal },+) => unknown | Promise<unknown>;++export type ToolRegistration<Context = undefined> = Omit<ToolDefinition, "name"> & {+ execute: ToolHandler<Context>;+};++export interface ToolExecutionRequest {+ name: string;+ arguments?: Record<string, unknown>;+ /** Complete generated response. Required for script names, optional for direct tools. */+ response?: string;+}++export type ToolExecutionOptions<Context = undefined> = {+ signal?: AbortSignal;+ /** Total execution budget, including customer tools. Default: 60 seconds. */+ timeoutMs?: number;+} & (undefined extends Context ? { context?: Context } : { context: Context });++export interface ToolExecutorOptions<Context = undefined> {+ tools: Record<string, ToolRegistration<Context>>;+ /** Required for generated scripts. Direct registered tools do not need a Gateway key. */+ apiKey?: string;+ /** Gateway origin, without /v1. Defaults to https://api.thesys.dev. */+ apiBaseUrl?: string;+ fetch?: typeof globalThis.fetch;+}++export interface RegisteredTools<Context = undefined> {+ definitions: ToolDefinition[];+ execute(+ input: ToolExecutionRequest,+ ...options: undefined extends Context+ ? [options?: ToolExecutionOptions<Context>]+ : [options: ToolExecutionOptions<Context>]+ ): Promise<unknown>;+}++export interface ScriptToolCall {+ type?: "function_call";+ call_id: string;+ name: string;+ arguments: string;+}++export type ScriptToolResult =+ | { type: "function_call_output"; call_id: string; output: string }+ | { call_id: string; error: { code: string; message: string } };++/** Execution failures expose a stable code and an optional HTTP status. */+export class ToolExecutionError extends Error {+ constructor(+ message: string,+ readonly code: string,+ readonly status?: number,+ ) {+ super(message);+ this.name = "ToolExecutionError";+ }+}