The Open Standard for Generative UI
Add artifactTool on @openuidev/lang-core/cloud (#1146)
AB923deba4d96f
diff --git a/docs/app/api/openui-cloud/chat/route.ts b/docs/app/api/openui-cloud/chat/route.tsindex 4dfe8f064..d4519e9ee 100644--- a/docs/app/api/openui-cloud/chat/route.ts+++ b/docs/app/api/openui-cloud/chat/route.ts@@ -3,7 +3,7 @@ import { unavailableResponse } from "@/lib/openui-cloud/errors";import { resolveRequestedModel } from "@/lib/openui-cloud/models";import { hasAllowedOrigin, hasJsonContentType, readLimitedJson } from "@/lib/openui-cloud/request";import { generateSystemPrompt } from "@openuidev/lang-core";-import { artifactTool } from "@openuidev/thesys-server";+import { artifactTool } from "@openuidev/lang-core/cloud";import OpenAI from "openai";import type { ResponseInputItem } from "openai/resources/responses/responses";diff --git a/docs/package.json b/docs/package.jsonindex f42c2d6cf..b31650421 100644--- a/docs/package.json+++ b/docs/package.json@@ -24,7 +24,6 @@"@openuidev/react-lang": "workspace:^","@openuidev/react-ui": "workspace:^","@openuidev/thesys": "0.3.2",- "@openuidev/thesys-server": "0.1.4","@phosphor-icons/react": "^2.1.10","@radix-ui/react-dialog": "1.1.15","@radix-ui/react-tooltip": "1.2.7",diff --git a/packages/lang-core/README.md b/packages/lang-core/README.mdindex cbf42ced0..2755f25fe 100644--- a/packages/lang-core/README.md+++ b/packages/lang-core/README.md@@ -96,6 +96,17 @@ const myLibraryPrompt = generateSystemPrompt({});```+Enable managed slides and reports with `artifactTool` from the Cloud subpath:++```ts+import { artifactTool } from "@openuidev/lang-core/cloud";++const tools = [+ artifactTool({ artifacts: ["slides", "report"] }),+ { type: "web_search" },+];+```+### Merge incremental edits```ts@@ -128,6 +139,12 @@ const merged = mergeStatements(original, patch);**`ToolSpec`** describes a tool for prompt generation (name, description, inputSchema, outputSchema). Shape inspired by MCP's tool schema.+### OpenUI Cloud++| Export | Description |+| :--- | :--- |+| `artifactTool(options?)` | From `@openuidev/lang-core/cloud`. Responses `tools[]` entry for Cloud's managed slides/report artifacts. |+## TelemetryLang Core sends pseudonymous installation telemetry during `postinstall`.diff --git a/packages/lang-core/package.json b/packages/lang-core/package.jsonindex 21cd5a8df..3427c9204 100644--- a/packages/lang-core/package.json+++ b/packages/lang-core/package.json@@ -1,12 +1,19 @@{"name": "@openuidev/lang-core",- "version": "0.2.17",+ "version": "0.2.18","description": "Framework-agnostic core for OpenUI Lang: parser, prompt generation, validation, and type definitions","license": "MIT","type": "module","main": "dist/index.cjs","module": "dist/index.mjs","types": "dist/index.d.cts",+ "typesVersions": {+ "*": {+ "cloud": [+ "dist/cloud.d.cts"+ ]+ }+ },"sideEffects": false,"files": ["dist",@@ -23,6 +30,16 @@"types": "./dist/index.d.cts","default": "./dist/index.cjs"}+ },+ "./cloud": {+ "import": {+ "types": "./dist/cloud.d.mts",+ "default": "./dist/cloud.mjs"+ },+ "require": {+ "types": "./dist/cloud.d.cts",+ "default": "./dist/cloud.cjs"+ }}},"scripts": {diff --git a/packages/lang-core/src/__tests__/cloud.test.ts b/packages/lang-core/src/__tests__/cloud.test.tsnew file mode 100644index 000000000..34e7fb3b7--- /dev/null+++ b/packages/lang-core/src/__tests__/cloud.test.ts@@ -0,0 +1,77 @@+import { describe, expect, it } from "vitest";+import { artifactTool, REPORT_LIBRARY_VERSION, SLIDES_LIBRARY_VERSION } from "../cloud";++const CLOUD_SUPPORTED_ARTIFACT_TYPES = ["slides", "report"];++describe("artifactTool — defaults", () => {+ const ALL_WITH_VERSION = {+ type: "artifact",+ artifacts: [+ { artifact_type: "slides", library_version: SLIDES_LIBRARY_VERSION },+ { artifact_type: "report", library_version: REPORT_LIBRARY_VERSION },+ ],+ };++ it("no options → all types WITH library_version", () => {+ expect(artifactTool()).toEqual(ALL_WITH_VERSION);+ });++ it("empty options → all types WITH library_version too", () => {+ expect(artifactTool({})).toEqual(ALL_WITH_VERSION);+ });+});++describe("artifactTool — restriction", () => {+ it("'slides' shorthand → entry with pinned version", () => {+ expect(artifactTool({ artifacts: ["slides"] })).toEqual({+ type: "artifact",+ artifacts: [{ artifact_type: "slides", library_version: SLIDES_LIBRARY_VERSION }],+ });+ });++ it("'report' shorthand → entry with pinned version", () => {+ expect(artifactTool({ artifacts: ["report"] })).toEqual({+ type: "artifact",+ artifacts: [{ artifact_type: "report", library_version: REPORT_LIBRARY_VERSION }],+ });+ });++ it("mixed shorthand + object entries, order preserved", () => {+ const entry = artifactTool({+ artifacts: [{ type: "slides", instruction: "Use the corporate template." }, "report"],+ });+ expect(entry.artifacts?.map((a) => a.artifact_type)).toEqual(["slides", "report"]);+ expect(entry.artifacts?.[0]?.instruction).toBe("Use the corporate template.");+ expect(entry.artifacts?.[1]).not.toHaveProperty("instruction");+ });++ it("every emitted artifact_type is Cloud-supported", () => {+ const entry = artifactTool({ artifacts: ["slides", "report"] });+ for (const a of entry.artifacts ?? []) {+ expect(CLOUD_SUPPORTED_ARTIFACT_TYPES).toContain(a.artifact_type);+ }+ });++ it("libraryVersion override wins over the pinned constant", () => {+ const entry = artifactTool({+ artifacts: [{ type: "report", libraryVersion: "2.3.0" }],+ });+ expect(entry.artifacts?.[0]?.library_version).toBe("2.3.0");+ });+});++describe("artifactTool — validation", () => {+ it("empty artifacts array throws (omit to enable all)", () => {+ expect(() => artifactTool({ artifacts: [] })).toThrow(/must not be empty/);+ });++ it("duplicate artifact kinds throw", () => {+ expect(() => artifactTool({ artifacts: ["report", { type: "report" }] })).toThrow(/duplicate/);+ });++ it("unknown artifact kind throws — incl. 'presentation' (not wire vocabulary)", () => {+ expect(() => artifactTool({ artifacts: ["presentation" as never] })).toThrow(+ /unknown artifact type 'presentation'/,+ );+ });+});diff --git a/packages/lang-core/src/cloud.ts b/packages/lang-core/src/cloud.tsnew file mode 100644index 000000000..ff03efba5--- /dev/null+++ b/packages/lang-core/src/cloud.ts@@ -0,0 +1,95 @@+export type ArtifactKind = "slides" | "report";++export interface ArtifactOption {+ type: ArtifactKind;+ /** Per-artifact instruction, folded into the Cloud tool description. */+ instruction?: string;+ /** Override this package's pinned library version for this artifact. */+ libraryVersion?: string;+}++export interface ArtifactToolOptions {+ /** Which artifacts to enable. Omit to enable all artifact types. */+ artifacts?: Array<ArtifactKind | ArtifactOption>;+}++export interface ArtifactWireEntry {+ artifact_type: ArtifactKind;+ instruction?: string;+ library_version?: string;+}++/** The Responses `tools[]` entry enabling OpenUI Cloud's managed artifact tool. */+export interface ResponsesArtifactToolEntry {+ type: "artifact";+ /** Absent → all supported artifact types enabled. */+ artifacts?: ArtifactWireEntry[];+}++/**+ * Wire pins for OpenUI Cloud's managed artifact libraries. Cloud rejects a+ * non-numeric or too-old version.+ */+export const SLIDES_LIBRARY_VERSION = "0.1.0";+export const REPORT_LIBRARY_VERSION = "0.1.0";++const DEFAULT_LIBRARY_VERSION: Record<ArtifactKind, string> = {+ slides: SLIDES_LIBRARY_VERSION,+ report: REPORT_LIBRARY_VERSION,+};++/**+ * Build the Responses `tools[]` entry that enables Cloud's managed artifact tool.+ *+ * tools: [artifactTool()] // all artifact types+ * tools: [artifactTool({ artifacts: ["report"] })] // report only+ * tools: [artifactTool({+ * artifacts: [+ * { type: "slides", instruction: "Use the corporate template." },+ * "report",+ * ],+ * })]+ *+ * Pass at most one artifactTool() entry per request — Cloud keys the+ * artifact config by tool type, so a second entry silently replaces the first.+ */+export function artifactTool(options: ArtifactToolOptions = {}): ResponsesArtifactToolEntry {+ const { artifacts } = options;+ if (artifacts === undefined) {+ // Emit every supported type WITH its library_version so Cloud resolves to+ // the OpenUI Lang format. A bare `{ type: "artifact" }` with no+ // library_version is the legacy shape — not what a lang-core caller wants.+ return {+ type: "artifact",+ artifacts: (Object.keys(DEFAULT_LIBRARY_VERSION) as ArtifactKind[]).map((kind) => ({+ artifact_type: kind,+ library_version: DEFAULT_LIBRARY_VERSION[kind],+ })),+ };+ }+ if (artifacts.length === 0) {+ throw new Error(+ "artifactTool: `artifacts` must not be empty — omit it to enable all artifact types.",+ );+ }++ const seen = new Set<ArtifactKind>();+ const entries: ArtifactWireEntry[] = artifacts.map((artifact) => {+ const opt: ArtifactOption = typeof artifact === "string" ? { type: artifact } : artifact;+ if (!(opt.type in DEFAULT_LIBRARY_VERSION)) {+ throw new Error(+ `artifactTool: unknown artifact type '${opt.type}'. Supported: ${Object.keys(DEFAULT_LIBRARY_VERSION).join(", ")}.`,+ );+ }+ if (seen.has(opt.type)) {+ throw new Error(`artifactTool: duplicate artifact '${opt.type}'.`);+ }+ seen.add(opt.type);+ return {+ artifact_type: opt.type,+ ...(opt.instruction && { instruction: opt.instruction }),+ library_version: opt.libraryVersion ?? DEFAULT_LIBRARY_VERSION[opt.type],+ };+ });+ return { type: "artifact", artifacts: entries };+}diff --git a/packages/lang-core/tsdown.config.ts b/packages/lang-core/tsdown.config.tsindex b805735df..49bc42591 100644--- a/packages/lang-core/tsdown.config.ts+++ b/packages/lang-core/tsdown.config.ts@@ -2,7 +2,7 @@ import { defineConfig } from "tsdown";import packageJson from "./package.json" with { type: "json" };export default defineConfig({- entry: ["src/index.ts", "src/postinstall.ts"],+ entry: ["src/index.ts", "src/postinstall.ts", "src/cloud.ts"],format: ["esm", "cjs"],dts: true,sourcemap: true,diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex 581f841e3..63518008f 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -84,9 +84,6 @@ importers:'@openuidev/thesys':specifier: 0.3.2version: 0.3.2(@openuidev/lang-core@packages+lang-core)(@openuidev/react-headless@packages+react-headless)(@openuidev/react-lang@packages+react-lang)(@openuidev/react-ui@packages+react-ui)(@radix-ui/[email protected](@types/[email protected](@types/[email protected]))(@types/[email protected])([email protected]([email protected]))([email protected]))(@tiptap/[email protected](@tiptap/[email protected]))(@tiptap/[email protected])(@types/[email protected](@types/[email protected]))(@types/[email protected])([email protected]([email protected]))([email protected])([email protected])([email protected](@types/[email protected])([email protected]))- '@openuidev/thesys-server':- specifier: 0.1.4- version: 0.1.4'@phosphor-icons/react':specifier: ^2.1.10@@ -2188,9 +2185,6 @@ packages:resolution: {integrity: sha512-eSYWTm620tTk45EKSedaUL8MFYI8hW164hIXsgIHyxu3VobUB3fFCu5t0hQby6OoWRPsG1KkKUG2M5UadiLiVg==}engines: {node: '>=14'}- '@openuidev/[email protected]':- resolution: {integrity: sha512-kRP54tk5608IuTU0Rjwo4wE8oCpWIxLAphhBkNGHaeZd7hAXwLGmT/vcIZBIr8KQM3Riq/pczrOa/ksyXXtcvQ==}-'@openuidev/[email protected]':resolution: {integrity: sha512-bVnVy2OcGawikt+R5QR4EBKtRvd0Y2PD9+Z94EClD5fSVtfi9VT9yztBp9a+r104SdB1GZuRuO3J/U+UALZgyg==}engines: {node: '>=20'}@@ -11639,8 +11633,6 @@ snapshots:'@opentelemetry/[email protected]':optional: true- '@openuidev/[email protected]': {}-'@openuidev/[email protected](@openuidev/lang-core@packages+lang-core)(@openuidev/react-headless@packages+react-headless)(@openuidev/react-lang@packages+react-lang)(@openuidev/react-ui@packages+react-ui)(@radix-ui/[email protected](@types/[email protected](@types/[email protected]))(@types/[email protected])([email protected]([email protected]))([email protected]))(@tiptap/[email protected](@tiptap/[email protected]))(@tiptap/[email protected])(@types/[email protected](@types/[email protected]))(@types/[email protected])([email protected]([email protected]))([email protected])([email protected])([email protected](@types/[email protected])([email protected]))':dependencies: