The Open Standard for Generative UI
Add a cloud flag to generateSystemPrompt in lang-core (#1117)
ABa1db90bc9481
diff --git a/docs/app/api/openui-cloud/chat/route.ts b/docs/app/api/openui-cloud/chat/route.tsindex e4e8797f6..4dfe8f064 100644--- a/docs/app/api/openui-cloud/chat/route.ts+++ b/docs/app/api/openui-cloud/chat/route.ts@@ -2,7 +2,8 @@ import { readOpenuiCloudConfig } from "@/lib/openui-cloud/config";import { unavailableResponse } from "@/lib/openui-cloud/errors";import { resolveRequestedModel } from "@/lib/openui-cloud/models";import { hasAllowedOrigin, hasJsonContentType, readLimitedJson } from "@/lib/openui-cloud/request";-import { artifactTool, generateSystemPrompt } from "@openuidev/thesys-server";+import { generateSystemPrompt } from "@openuidev/lang-core";+import { artifactTool } from "@openuidev/thesys-server";import OpenAI from "openai";import type { ResponseInputItem } from "openai/resources/responses/responses";@@ -56,6 +57,7 @@ export async function POST(request: Request): Promise<Response> {{ type: "image_search" },],instructions: generateSystemPrompt({+ cloud: true,instructions:"When creating an artifact, actively use the available web and image search tools to ground its content and visual choices.",}),diff --git a/docs/content/docs/openui-cloud/api/chat-completions.mdx b/docs/content/docs/openui-cloud/api/chat-completions.mdxindex 08c9f9224..8b44cf59b 100644--- a/docs/content/docs/openui-cloud/api/chat-completions.mdx+++ b/docs/content/docs/openui-cloud/api/chat-completions.mdx@@ -14,12 +14,12 @@ Use the `embedClient` from the [API overview](/docs/openui-cloud/api/overview),Use the server helper to have OpenUI Cloud assemble the system prompt for its built-in component library.```ts title="server.ts"-import { generateSystemPrompt } from "@openuidev/thesys-server";+import { generateSystemPrompt } from "@openuidev/lang-core";const completion = await embedClient.chat.completions.create({model: "openai/gpt-5",messages: [- { role: "system", content: generateSystemPrompt() },+ { role: "system", content: generateSystemPrompt({ cloud: true }) },{ role: "user", content: "Compare quarterly revenue by region." },],});@@ -27,7 +27,7 @@ const completion = await embedClient.chat.completions.create({console.log(completion.choices[0].message.content);```-The returned message content is an OpenUI Lang program. See [Component Library](/docs/openui-cloud/build/component-library) for the built-in client library and custom component workflow.+The returned message content is an OpenUI Lang program. See [Component Library](/docs/openui-cloud/build/component-library) for the built-in client library and using your own library.## Stream and render responses@@ -75,7 +75,7 @@ Hosted `web_search`, `image_search`, remote MCP, and artifacts-as-tool are avail### Plain text passthrough-Use a `{provider}/{model}` model ID without the managed `generateSystemPrompt()` sentinel. OpenUI Cloud forwards your messages and system prompt without injecting a generative UI prompt or component schema.+Use a `{provider}/{model}` model ID without the managed `generateSystemPrompt({ cloud: true })` sentinel. OpenUI Cloud forwards your messages and system prompt without injecting a generative UI prompt or component schema.```tsconst completion = await embedClient.chat.completions.create({diff --git a/docs/content/docs/openui-cloud/api/conversations.mdx b/docs/content/docs/openui-cloud/api/conversations.mdxindex 442ff7cf3..eb5d83cfd 100644--- a/docs/content/docs/openui-cloud/api/conversations.mdx+++ b/docs/content/docs/openui-cloud/api/conversations.mdx@@ -27,13 +27,13 @@ const conversation = await conversationClient.conversations.create({Then send only the new turn to Responses and set `store: true`:```ts-import { generateSystemPrompt } from "@openuidev/thesys-server";+import { generateSystemPrompt } from "@openuidev/lang-core";const response = await embedClient.responses.create({model: "openai/gpt-5",conversation: conversation.id,input: "Compare quarterly revenue by region.",- instructions: generateSystemPrompt(),+ instructions: generateSystemPrompt({ cloud: true }),store: true,stream: true,});diff --git a/docs/content/docs/openui-cloud/api/responses.mdx b/docs/content/docs/openui-cloud/api/responses.mdxindex 98d898c72..61d03d9e2 100644--- a/docs/content/docs/openui-cloud/api/responses.mdx+++ b/docs/content/docs/openui-cloud/api/responses.mdx@@ -14,18 +14,18 @@ Use the `embedClient` from the [API overview](/docs/openui-cloud/api/overview),Use the server helper to have OpenUI Cloud assemble the system prompt for its built-in component library.```ts title="server.ts"-import { generateSystemPrompt } from "@openuidev/thesys-server";+import { generateSystemPrompt } from "@openuidev/lang-core";const response = await embedClient.responses.create({model: "openai/gpt-5",input: "Compare quarterly revenue by region.",- instructions: generateSystemPrompt(),+ instructions: generateSystemPrompt({ cloud: true }),});console.log(response.output_text);```-The returned `output_text` is an OpenUI Lang program. See [Component Library](/docs/openui-cloud/build/component-library) for the built-in client library and custom component workflow.+The returned `output_text` is an OpenUI Lang program. See [Component Library](/docs/openui-cloud/build/component-library) for the built-in client library and using your own library.## Stream and render responses@@ -72,14 +72,14 @@ Chain a follow-up to an earlier response:const first = await embedClient.responses.create({model: "openai/gpt-5",input: "Compare quarterly revenue by region.",- instructions: generateSystemPrompt(),+ instructions: generateSystemPrompt({ cloud: true }),store: true,});const followUp = await embedClient.responses.create({model: "openai/gpt-5",input: "Focus on Europe and explain the change.",- instructions: generateSystemPrompt(),+ instructions: generateSystemPrompt({ cloud: true }),previous_response_id: first.id,store: true,});@@ -105,7 +105,7 @@ import type { Tool } from "openai/resources/responses/responses";const response = await embedClient.responses.create({model: "openai/gpt-5",input: "Research the market and summarize the most important changes.",- instructions: generateSystemPrompt(),+ instructions: generateSystemPrompt({ cloud: true }),tools: [{ type: "web_search" },{ type: "image_search" } as unknown as Tool,@@ -129,14 +129,15 @@ For a `function` tool, execute each returned `function_call` on your server andAdd `artifactTool()` to generate editable slides or reports inside the agent stream:```ts-import { artifactTool, generateSystemPrompt } from "@openuidev/thesys-server";+import { generateSystemPrompt } from "@openuidev/lang-core";+import { artifactTool } from "@openuidev/thesys-server";import type { Tool } from "openai/resources/responses/responses";const response = await embedClient.responses.create({model: "openai/gpt-5",conversation: threadId,input: "Create a three-slide deck on Q4 results.",- instructions: generateSystemPrompt(),+ instructions: generateSystemPrompt({ cloud: true }),tools: [artifactTool({ artifacts: ["slides", "report"] }) as unknown as Tool],store: true,stream: true,diff --git a/docs/content/docs/openui-cloud/build/component-library.mdx b/docs/content/docs/openui-cloud/build/component-library.mdxindex 376cfa548..9243cd481 100644--- a/docs/content/docs/openui-cloud/build/component-library.mdx+++ b/docs/content/docs/openui-cloud/build/component-library.mdx@@ -15,18 +15,19 @@ import { chatLibrary } from "@openuidev/thesys";<AgentInterface llm={llm} componentLibrary={chatLibrary} />;```-On the backend, `generateSystemPrompt()` uses the built-in library by default. Use the `embedClient` from the [API overview](/docs/openui-cloud/api/overview); the placement of the generated instructions depends on the API:+On the backend, `generateSystemPrompt({ cloud: true })` uses the built-in library by default. Use the `embedClient` from the [API overview](/docs/openui-cloud/api/overview); the placement of the generated instructions depends on the API:<Tabs groupId="cloud-api" items={["Responses", "Chat Completions"]} persist><Tab value="Responses">```ts-import { generateSystemPrompt } from "@openuidev/thesys-server";+import { generateSystemPrompt } from "@openuidev/lang-core";const response = await embedClient.responses.create({model: "openai/gpt-5",input: "Show revenue by region as an interactive dashboard.",instructions: generateSystemPrompt({+ cloud: true,instructions: "Optional instructions for the model.",}),});@@ -36,7 +37,7 @@ const response = await embedClient.responses.create({<Tab value="Chat Completions">```ts-import { generateSystemPrompt } from "@openuidev/thesys-server";+import { generateSystemPrompt } from "@openuidev/lang-core";const completion = await embedClient.chat.completions.create({model: "openai/gpt-5",@@ -44,6 +45,7 @@ const completion = await embedClient.chat.completions.create({{role: "system",content: generateSystemPrompt({+ cloud: true,instructions: "Optional instructions for the model.",}),},@@ -123,6 +125,7 @@ npx @openuidev/cli@latest generate --spec src/lib/chat-library.tsx --out ./genermodel: "openai/gpt-5",input,instructions: generateSystemPrompt({+ cloud: true,instructions: "Optional instructions for the model.",+ library: librarySpec,+ promptOptions: { preamble: "You build dashboards for Acme operators." },@@ -142,6 +145,7 @@ npx @openuidev/cli@latest generate --spec src/lib/chat-library.tsx --out ./gener{role: "system",content: generateSystemPrompt({+ cloud: true,instructions: "Optional instructions for the model.",+ library: librarySpec,+ promptOptions: { preamble: "You build dashboards for Acme operators." },diff --git a/docs/content/docs/openui-lang/examples/agent-frameworks/vercel-ai-sdk.mdx b/docs/content/docs/openui-lang/examples/agent-frameworks/vercel-ai-sdk.mdxindex ec539e69e..bd3ef3772 100644--- a/docs/content/docs/openui-lang/examples/agent-frameworks/vercel-ai-sdk.mdx+++ b/docs/content/docs/openui-lang/examples/agent-frameworks/vercel-ai-sdk.mdx@@ -22,7 +22,7 @@ This example uses the [Vercel AI SDK](https://ai-sdk.dev/) (`streamText`, `tool(## How it connects-The API route calls `streamText` with Cloud Completions, `generateSystemPrompt()`, and tools defined with `tool()`. When the model calls a tool, the AI SDK executes it server-side and continues — up to 5 steps. The response is a UIMessage stream.+The API route calls `streamText` with Cloud Completions, `generateSystemPrompt({ cloud: true })`, and tools defined with `tool()`. When the model calls a tool, the AI SDK executes it server-side and continues — up to 5 steps. The response is a UIMessage stream.The page passes that stream to `<AgentInterface />`:@@ -54,7 +54,7 @@ Storage is omitted, so AgentInterface uses its built-in in-memory default (wiped```tsimport { createOpenAI } from "@ai-sdk/openai";-import { generateSystemPrompt } from "@openuidev/thesys-server";+import { generateSystemPrompt } from "@openuidev/lang-core";import { convertToModelMessages, stepCountIs, streamText } from "ai";import { tools } from "@/lib/tools";@@ -67,7 +67,7 @@ export async function POST(req: Request) {const { messages } = await req.json();const result = streamText({model: openai.chat("google/gemini-3.6-flash-free"),- system: generateSystemPrompt(),+ system: generateSystemPrompt({ cloud: true }),messages: await convertToModelMessages(messages),tools,stopWhen: stepCountIs(5),diff --git a/docs/content/docs/openui-lang/quickstart.mdx b/docs/content/docs/openui-lang/quickstart.mdxindex e1b0ec369..f3332ec0f 100644--- a/docs/content/docs/openui-lang/quickstart.mdx+++ b/docs/content/docs/openui-lang/quickstart.mdx@@ -297,8 +297,9 @@ Never claim that a recipe is allergen-safe.Update the `instructions` field inside `createParams`:<CopyableDiff- code={`-instructions: generateSystemPrompt(),+ code={`-instructions: generateSystemPrompt({ cloud: true }),+instructions: generateSystemPrompt({++ cloud: true,+ library: recipeLibrarySpec,+ instructions: recipeInstructions,+}),`}diff --git a/docs/content/docs/openui-lang/system-prompts.mdx b/docs/content/docs/openui-lang/system-prompts.mdxindex e77af5454..d2dbae0e7 100644--- a/docs/content/docs/openui-lang/system-prompts.mdx+++ b/docs/content/docs/openui-lang/system-prompts.mdx@@ -71,7 +71,7 @@ const systemPrompt = generateSystemPrompt({editMode: true, // Enable incremental editing (LLM outputs patches, not full regen)inlineMode: true, // Enable text + code responses (LLM can answer questions without code)- // Custom instructions+ // Preamble and extra rulespreamble: "You build dashboards using openui-lang.",additionalRules: ['Use @Reset after form submit, not @Set($var, "")'],},@@ -85,6 +85,28 @@ const systemPrompt = generateSystemPrompt({| `editMode` | Incremental editing - LLM outputs only changed statements | `false` || `inlineMode` | Text + fenced code responses - LLM can answer questions without generating UI | `false` |+### OpenUI Cloud++Pass `cloud: true` to emit Cloud's managed config block instead of a local prompt. OpenUI Cloud assembles the real system prompt on the server. `instructions` is Cloud-only extra prose appended after the config block.++```ts+import { generateSystemPrompt } from "@openuidev/lang-core";++const instructions = generateSystemPrompt({ cloud: true });+```++With your own library, pass the generated spec:++```ts+const instructions = generateSystemPrompt({+ cloud: true,+ library: librarySpec,+ promptOptions: { preamble: "You build dashboards for Acme." },+});+```++See [Component Library](/docs/openui-cloud/build/component-library) for the Cloud workflow.+Built-in functions (`@Count`, `@Filter`, `@Sort`, `@Each`, etc.) are automatically included when either `toolCalls` or `bindings` is enabled. For static UI libraries without data fetching, they are omitted to keep the prompt concise.### `library.prompt()` (frontend shorthand)diff --git a/packages/lang-core/README.md b/packages/lang-core/README.mdindex 453222ec7..cbf42ced0 100644--- a/packages/lang-core/README.md+++ b/packages/lang-core/README.md@@ -61,16 +61,38 @@ const result2 = sp.set("root = Stack([header])\nheader = CardHeader(\"Hello\")\n### Generate a system prompt```ts-import { generatePrompt, type PromptSpec } from "@openuidev/lang-core";-import componentSpec from "./generated/component-spec.json";--const prompt = generatePrompt({- ...componentSpec,- tools: myToolSpecs,- toolCalls: true,- bindings: true,- editMode: true,- preamble: "You build dashboards.",+import { generateSystemPrompt, type LibrarySpec } from "@openuidev/lang-core";+import librarySpec from "./generated/library.spec.json";++const prompt = generateSystemPrompt({+ library: librarySpec as LibrarySpec,+ promptOptions: {+ tools: myToolSpecs,+ toolCalls: true,+ bindings: true,+ editMode: true,+ preamble: "You build dashboards.",+ },+});+```++### OpenUI Cloud++Pass `cloud: true` to emit Cloud's managed config block instead of a local prompt. OpenUI Cloud+assembles the real system prompt on the server.++```ts+import { generateSystemPrompt } from "@openuidev/lang-core";++// Built-in Cloud chat library+const instructions = generateSystemPrompt({ cloud: true });++// Using your own library (the `.spec.json` from `openui generate`)+const myLibraryPrompt = generateSystemPrompt({+ cloud: true,+ library: librarySpec,+ promptOptions: { preamble: "You build dashboards for Acme." },+ instructions: "Be terse.",});```@@ -99,7 +121,8 @@ const merged = mergeStatements(original, patch);| Export | Description || :--- | :--- |-| `generatePrompt(spec)` | Generate a system prompt from a `PromptSpec` |+| `generatePrompt(spec)` | Generate a system prompt from a `PromptSpec` (now deprecated) |+| `generateSystemPrompt(spec)` | Generate a system prompt from `{ library, promptOptions }`. Pass `{ cloud: true }` for OpenUI Cloud's managed config. |**`PromptSpec`** includes component signatures, tool definitions (`ToolSpec[]`), feature flags (`toolCalls`, `bindings`, `editMode`, `inlineMode`), examples, and custom rules.diff --git a/packages/lang-core/package.json b/packages/lang-core/package.jsonindex 74faebda3..21cd5a8df 100644--- a/packages/lang-core/package.json+++ b/packages/lang-core/package.json@@ -1,6 +1,6 @@{"name": "@openuidev/lang-core",- "version": "0.2.16",+ "version": "0.2.17","description": "Framework-agnostic core for OpenUI Lang: parser, prompt generation, validation, and type definitions","license": "MIT","type": "module",diff --git a/packages/lang-core/src/index.ts b/packages/lang-core/src/index.tsindex cc10b3933..8fc38cf4f 100644--- a/packages/lang-core/src/index.ts+++ b/packages/lang-core/src/index.ts@@ -35,6 +35,7 @@ export { tokenize } from "./parser/lexer";export { mergeStatements } from "./parser/merge";export { generatePrompt, generateSystemPrompt } from "./parser/prompt";export type {+ CloudPromptOptions,ComponentPromptSpec,LibrarySpec,PromptSpec,diff --git a/packages/lang-core/src/parser/__tests__/prompt.test.ts b/packages/lang-core/src/parser/__tests__/prompt.test.tsnew file mode 100644index 000000000..24c1ca94e--- /dev/null+++ b/packages/lang-core/src/parser/__tests__/prompt.test.ts@@ -0,0 +1,175 @@+import { describe, expect, it } from "vitest";+import { generateSystemPrompt, type CloudPromptOptions, type LibrarySpec } from "../../index";++const CONFIG_MARKER = "]]>openui:config\n";++const CLOUD_CONFIG_KEYS = [+ "libraryVersion",+ "customComponents",+ "customActions",+ "openrouterProvider",+ "chatLibrary",+ "systemPromptOptions",+];++function parseBlock(emitted: string): Record<string, unknown> {+ expect(emitted.startsWith(CONFIG_MARKER)).toBe(true);+ const body = emitted.slice(CONFIG_MARKER.length);+ const firstLine = body.split("\n", 1)[0];+ return JSON.parse(firstLine);+}++const library = {+ root: "Card",+ schema: {+ $defs: {+ Card: {+ properties: {+ children: {+ type: "array",+ items: { anyOf: [{ $ref: "#/$defs/TextContent" }] },+ },+ title: { type: "string" },+ },+ required: ["children"],+ description: "Top-level container.",+ },+ TextContent: {+ properties: { text: { type: "string" } },+ required: ["text"],+ },+ },+ },+ componentGroups: [+ {+ name: "Content",+ components: ["TextContent"],+ },+ ],+} as LibrarySpec;++describe("generateSystemPrompt — self-hosted", () => {+ const spec: LibrarySpec = {+ root: "Card",+ components: {+ Card: { signature: "Card(children: Component[])", description: "Root" },+ },+ };++ it("renders a local prompt from a library spec", () => {+ const prompt = generateSystemPrompt({ library: spec });+ expect(prompt).toContain("openui-lang");+ expect(prompt).toContain("Card(children: Component[])");+ expect(prompt.startsWith(CONFIG_MARKER)).toBe(false);+ });+});++describe("generateSystemPrompt({ cloud: true }) — sentinel", () => {+ it("starts with the byte-exact marker", () => {+ const out = generateSystemPrompt({ cloud: true });+ expect(out.slice(0, CONFIG_MARKER.length)).toBe(CONFIG_MARKER);+ });++ it("no library → JSON with only libraryVersion", () => {+ const config = parseBlock(generateSystemPrompt({ cloud: true }));+ expect(Object.keys(config)).toEqual(["libraryVersion"]);+ expect(config.libraryVersion).toBe("0.1.0");+ });++ it("emitted keys are a subset of Cloud config keys", () => {+ const config = parseBlock(generateSystemPrompt({ cloud: true, instructions: "Be terse." }));+ for (const key of Object.keys(config)) {+ expect(CLOUD_CONFIG_KEYS).toContain(key);+ }+ });++ it("appends extra prose after the block", () => {+ const out = generateSystemPrompt({ cloud: true, instructions: "Be terse." });+ const [sentinelLine, jsonLine, ...rest] = out.split("\n");+ expect(sentinelLine).toBe("]]>openui:config");+ expect(() => JSON.parse(jsonLine)).not.toThrow();+ expect(rest.join("\n")).toBe("Be terse.");+ });++ it("no instructions → sentinel + JSON only", () => {+ expect(generateSystemPrompt({ cloud: true }).split("\n")).toHaveLength(2);+ });+});++describe("generateSystemPrompt({ cloud: true, library })", () => {+ it("emits the library under chatLibrary, dropping components", () => {+ const specJson = {+ ...library,+ components: {+ Card: { signature: "Card(children: (TextContent)[], title?: string)" },+ },+ };+ const config = parseBlock(generateSystemPrompt({ cloud: true, library: specJson }));+ expect((config.chatLibrary as Record<string, unknown>).components).toBeUndefined();+ expect(config.chatLibrary).toEqual(library);+ expect(Object.keys(config)).toEqual(["chatLibrary"]);+ });++ it("systemPromptOptions rides as a sibling key", () => {+ const config = parseBlock(+ generateSystemPrompt({+ cloud: true,+ library,+ promptOptions: { preamble: "You generate UI for Acme." },+ }),+ );+ expect(Object.keys(config)).toEqual(["chatLibrary", "systemPromptOptions"]);+ expect(config.systemPromptOptions).toEqual({ preamble: "You generate UI for Acme." });+ });++ it("strips Cloud-unsupported prompt flags from the wire", () => {+ const config = parseBlock(+ generateSystemPrompt({+ cloud: true,+ library,+ promptOptions: {+ preamble: "Acme.",+ editMode: true,+ tools: ["search"],+ } as CloudPromptOptions,+ }),+ );+ expect(config.systemPromptOptions).toEqual({ preamble: "Acme." });+ });++ it("promptOptions without a library throws", () => {+ expect(() =>+ generateSystemPrompt({+ cloud: true,+ promptOptions: { preamble: "Nope." },+ }),+ ).toThrowError(/promptOptions requires a library/);+ });++ it("invalid library throws with every issue", () => {+ const broken: LibrarySpec = {+ root: "Missing",+ components: {},+ schema: {+ $defs: {+ Card: {+ properties: { body: { $ref: "#/$defs/Nope" } },+ required: ["ghost"],+ },+ },+ },+ };+ expect(() => generateSystemPrompt({ cloud: true, library: broken })).toThrowError(+ /Invalid library/,+ );+ expect(() => generateSystemPrompt({ cloud: true, library: broken })).toThrowError(+ /Root component "Missing"/,+ );+ expect(() => generateSystemPrompt({ cloud: true, library: broken })).toThrowError(+ /Unresolvable \$ref "#\/\$defs\/Nope"/,+ );+ expect(() => generateSystemPrompt({ cloud: true, library: broken })).toThrowError(+ /required property "ghost"/,+ );+ });+});diff --git a/packages/lang-core/src/parser/cloud-config.ts b/packages/lang-core/src/parser/cloud-config.tsnew file mode 100644index 000000000..7dfdff373--- /dev/null+++ b/packages/lang-core/src/parser/cloud-config.ts@@ -0,0 +1,59 @@+import type { CloudPromptOptions, LibrarySpec, SystemPromptOptions } from "./prompt";+import { validateChatLibrary } from "./validate-library";++/** `]]>openui:config\n` — request-direction config block header. Trailing newline is part of the wire contract. */+const CLOUD_CONFIG_MARKER = "]]>openui:config\n";++/**+ * Wire pin for OpenUI Cloud's built-in chat library when `generateSystemPrompt({ cloud: true })`+ * is called without your own library. Cloud rejects a non-numeric or too-old version.+ */+const CLOUD_CHAT_LIBRARY_VERSION = "0.1.0";++type CloudConfig =+ | { libraryVersion: string }+ | { chatLibrary: Omit<LibrarySpec, "components">; systemPromptOptions?: CloudPromptOptions };++function pickCloudPromptOptions(+ options: SystemPromptOptions | CloudPromptOptions | undefined,+): CloudPromptOptions | undefined {+ if (!options) return undefined;+ const picked: CloudPromptOptions = {};+ if (options.examples) picked.examples = options.examples;+ if (options.preamble) picked.preamble = options.preamble;+ if (options.additionalRules) picked.additionalRules = options.additionalRules;+ return Object.keys(picked).length > 0 ? picked : undefined;+}++export function generateCloudConfig(spec: {+ library?: LibrarySpec;+ promptOptions?: SystemPromptOptions | CloudPromptOptions;+ instructions?: string;+}): string {+ let config: CloudConfig;++ if (spec.library) {+ const issues = validateChatLibrary(spec.library);+ if (issues.length > 0) {+ throw new Error(+ `[generateSystemPrompt] Invalid library: ${issues.map((i) => i.message).join(" ")}`,+ );+ }+ const { components: _components, ...chatLibrary } = spec.library;+ const promptOptions = pickCloudPromptOptions(spec.promptOptions);+ config = {+ chatLibrary,+ ...(promptOptions ? { systemPromptOptions: promptOptions } : {}),+ };+ } else {+ if (spec.promptOptions && pickCloudPromptOptions(spec.promptOptions)) {+ throw new Error(+ "[generateSystemPrompt] promptOptions requires a library — the built-in library ignores it.",+ );+ }+ config = { libraryVersion: CLOUD_CHAT_LIBRARY_VERSION };+ }++ const block = `${CLOUD_CONFIG_MARKER}${JSON.stringify(config)}`;+ return spec.instructions ? `${block}\n${spec.instructions}` : block;+}diff --git a/packages/lang-core/src/parser/prompt.ts b/packages/lang-core/src/parser/prompt.tsindex d6ea9a76d..28f8da017 100644--- a/packages/lang-core/src/parser/prompt.ts+++ b/packages/lang-core/src/parser/prompt.ts@@ -1,5 +1,6 @@import { recordSystemPromptGeneration } from "../telemetry/runtime";import { BUILTINS, LAZY_BUILTIN_DEFS } from "./builtins";+import { generateCloudConfig } from "./cloud-config";import type { LibraryJSONSchema } from "./types";// ─── PromptSpec types (JSON-serializable, no Zod deps) ──────────────────────@@ -694,22 +695,49 @@ export function generatePrompt(spec: PromptSpec): string {return parts.join("\n");}-// ─── System prompt (library + options + instructions) ───────────────────────+// ─── System prompt (library + options) ──────────────────────────────────────/** Prompt options for {@link generateSystemPrompt} */export type SystemPromptOptions = Omit<PromptSpec, keyof BaseSpec>;-/** Object input for {@link generateSystemPrompt}. */-export interface SystemPromptSpec {- library: LibrarySpec;- promptOptions?: SystemPromptOptions;-}+/**+ * Prompt options allowed on the OpenUI Cloud wire. Extra flags (`tools`,+ * `editMode`, …) are stripped — Cloud's built-in prompt assembler ignores them.+ */+export type CloudPromptOptions = Pick<+ SystemPromptOptions,+ "examples" | "preamble" | "additionalRules"+>;-/** Render the full system prompt for a library. */+/**+ * Object input for {@link generateSystemPrompt}.+ *+ * Pass `cloud: true` to emit OpenUI Cloud's managed `]]>openui:config` block+ * instead of a locally generated prompt. In that mode `library` is optional —+ * omit it to use Cloud's built-in chat library. `instructions` is Cloud-only+ * extra prose appended after the config block.+ */+export type SystemPromptSpec =+ | {+ library: LibrarySpec;+ promptOptions?: SystemPromptOptions;+ cloud?: false;+ }+ | {+ cloud: true;+ library?: LibrarySpec;+ promptOptions?: CloudPromptOptions;+ instructions?: string;+ };++/** Render the full system prompt for a library, or Cloud's managed config block when `cloud: true`. */export function generateSystemPrompt(spec: SystemPromptSpec): string;-/** @deprecated Pass `{ library, promptOptions, instructions }` instead. Removed at the next major. */+/** @deprecated Pass `{ library, promptOptions }` instead. Removed at the next major. */export function generateSystemPrompt(spec: PromptSpec): string;export function generateSystemPrompt(spec: SystemPromptSpec | PromptSpec): string {+ if (isCloudSpec(spec)) {+ return generateCloudConfig(spec);+ }if (!isSystemPromptSpec(spec)) {const prompt = generatePrompt(spec);recordSystemPromptGeneration(spec, "legacy_prompt_spec");@@ -721,7 +749,14 @@ export function generateSystemPrompt(spec: SystemPromptSpec | PromptSpec): strinreturn prompt;}-// use `library` to discriminate SystemPromptSpec from the deprecated base-PromptSpec-function isSystemPromptSpec(spec: SystemPromptSpec | PromptSpec): spec is SystemPromptSpec {- return "library" in spec && typeof (spec as SystemPromptSpec).library === "object";+function isCloudSpec(+ spec: SystemPromptSpec | PromptSpec,+): spec is Extract<SystemPromptSpec, { cloud: true }> {+ return "cloud" in spec && (spec as { cloud?: unknown }).cloud === true;+}++function isSystemPromptSpec(+ spec: SystemPromptSpec | PromptSpec,+): spec is Extract<SystemPromptSpec, { library: LibrarySpec }> {+ return "library" in spec && typeof (spec as { library?: unknown }).library === "object";}diff --git a/packages/lang-core/src/parser/validate-library.ts b/packages/lang-core/src/parser/validate-library.tsnew file mode 100644index 000000000..32af9aa6e--- /dev/null+++ b/packages/lang-core/src/parser/validate-library.ts@@ -0,0 +1,182 @@+/**+ * Structural validator for your own library.+ * Hand-rolled walker — reports every issue in one pass.+ */+import type { LibrarySpec } from "./prompt";++export interface ChatLibraryIssue {+ code:+ | "invalid-shape"+ | "root-not-found"+ | "unresolved-ref"+ | "unknown-group-component"+ | "invalid-required";+ message: string;+ /** e.g. "$defs/Card/properties/children/items" */+ path?: string;+}++const REF_PATTERN = /^#\/\$defs\/(.+)$/;++function isPlainObject(value: unknown): value is Record<string, unknown> {+ return typeof value === "object" && value !== null && !Array.isArray(value);+}++/** Recursively collect every `$ref` and check it resolves within `$defs`. */+function collectRefIssues(+ node: unknown,+ path: string,+ defNames: Set<string>,+ issues: ChatLibraryIssue[],+): void {+ if (Array.isArray(node)) {+ node.forEach((item, i) => collectRefIssues(item, `${path}/${i}`, defNames, issues));+ return;+ }+ if (!isPlainObject(node)) return;++ const ref = node["$ref"];+ if (typeof ref === "string") {+ const match = REF_PATTERN.exec(ref);+ if (!match || !defNames.has(match[1] as string)) {+ issues.push({+ code: "unresolved-ref",+ message: `Unresolvable $ref "${ref}" at ${path} — refs must be "#/$defs/<name>" pointing at a component in $defs.`,+ path,+ });+ }+ }++ for (const [key, value] of Object.entries(node)) {+ if (key === "$ref") continue;+ collectRefIssues(value, `${path}/${key}`, defNames, issues);+ }+}++/**+ * Structural validation of your own library.+ * Returns ALL issues found (empty array = valid).+ */+export function validateChatLibrary(library: LibrarySpec): ChatLibraryIssue[] {+ const issues: ChatLibraryIssue[] = [];++ if (!isPlainObject(library)) {+ return [+ {+ code: "invalid-shape",+ message: "chatLibrary must be an object.",+ },+ ];+ }++ const { root, schema, componentGroups } = library;++ if (root !== undefined && (typeof root !== "string" || root.length === 0)) {+ issues.push({+ code: "invalid-shape",+ message: "chatLibrary.root, when present, must be a non-empty string.",+ path: "root",+ });+ }++ if (!isPlainObject(schema)) {+ issues.push({+ code: "invalid-shape",+ message: "chatLibrary.schema must be an object with a $defs map of component schemas.",+ path: "schema",+ });+ return issues;+ }++ const defs = schema.$defs;+ if (!isPlainObject(defs) || Object.keys(defs).length === 0) {+ issues.push({+ code: "invalid-shape",+ message: "chatLibrary.schema.$defs must be a non-empty object keyed by component name.",+ path: "schema/$defs",+ });+ return issues;+ }++ const defNames = new Set(Object.keys(defs));++ if (typeof root === "string" && root.length > 0 && !defNames.has(root)) {+ issues.push({+ code: "root-not-found",+ message: `Root component "${root}" was not found in schema.$defs. Available components: ${[...defNames].join(", ")}.`,+ path: "root",+ });+ }++ for (const [name, def] of Object.entries(defs)) {+ const defPath = `$defs/${name}`;+ if (!isPlainObject(def)) {+ issues.push({+ code: "invalid-shape",+ message: `${defPath} must be an object component schema.`,+ path: defPath,+ });+ continue;+ }++ const properties = def["properties"];+ if (properties !== undefined && !isPlainObject(properties)) {+ issues.push({+ code: "invalid-shape",+ message: `${defPath}/properties must be an object.`,+ path: `${defPath}/properties`,+ });+ }++ const required = def["required"];+ if (required !== undefined) {+ if (!Array.isArray(required) || required.some((r) => typeof r !== "string")) {+ issues.push({+ code: "invalid-required",+ message: `${defPath}/required must be an array of property names.`,+ path: `${defPath}/required`,+ });+ } else {+ const propKeys = new Set(isPlainObject(properties) ? Object.keys(properties) : []);+ for (const r of required) {+ if (!propKeys.has(r)) {+ issues.push({+ code: "invalid-required",+ message: `${defPath} lists required property "${r}" that is not in properties.`,+ path: `${defPath}/required`,+ });+ }+ }+ }+ }++ collectRefIssues(properties, `${defPath}/properties`, defNames, issues);+ }++ for (const group of componentGroups ?? []) {+ if (+ !isPlainObject(group) ||+ typeof group.name !== "string" ||+ !Array.isArray(group.components)+ ) {+ issues.push({+ code: "invalid-shape",+ message:+ "Each componentGroups entry must be {name: string, components: string[], notes?: string[]}.",+ path: "componentGroups",+ });+ continue;+ }+ for (const comp of group.components) {+ if (typeof comp !== "string" || !defNames.has(comp)) {+ issues.push({+ code: "unknown-group-component",+ message: `Component group "${group.name}" references unknown component "${String(comp)}".`,+ path: "componentGroups",+ });+ }+ }+ }++ return issues;+}